app.organization-planning-host

@lssm-tech/app.organization-planning-host

Website: https://contractspec.io

Thin OPA host — mounts the organization-planning operation registry on REST, GraphQL, and MCP.

What It Provides

• Couche: app. (thin deployable host; transport wiring only).
• Exposes buildOpaOps() (from @lssm-tech/lib.organization-planning-runtime) identically on three surfaces via existing contracts-runtime adapters:
  • REST — createOpaRestHandler(ctxFactory), served by the Next App Router catch-all at app/api/ops/[...route]/route.ts.
  • GraphQL — createOpaGraphqlBuilder() returns a Pothos builder with the OPA query/mutation fields.
  • MCP — mountOpaMcp(server, ctxFactories) registers the OPA tools.
• Serves the public booking page at app/book/[link]/page.tsx. The page speaks the OPA v2 public booking protocol through @lssm-tech/opa-booking-react (useOpaBooking plus the typed ./availability projections): anonymous visitors load the availability quote, pick a slot and create a booking intent bound to its availabilityRef/slotRef. The booking link must allowlist this host's origin; only name, email, timezone and locale are sent.

Auth

Fail-closed at every step. The REST route (app/api/ops/[...route]/route.ts) composes three pieces:

1. Session projection (src/session-context.ts, createOpaHostSessionContext). An Authorization: Bearer token is checked against AuthOS (/api/auth/get-session, through createBetterAuthBearerSessionReader) and then against the caller's own CompanyOS authority (GET /api/companyos/auth/authority, same bearer, no cookies or redirects, 1.5 s budget, answer at most 5 s old). The session and active organization must match, and the identity is read again after the authority read. The result is { actor: 'user', userId, organizationId, tenantId, workspaceId, roles }, where tenantId/workspaceId use the OPA ref grammar (tenant:<segment>, workspace:<segment>) and roles is the CompanyOS persona (grantRole). Anything else is { actor: 'anonymous' }, which the REST adapter rejects with 401 on every non-public operation. Module entitlement (src/opa-workspace-module.ts). Like the monolith's requireWorkspaceModule(session, 'opa'), the host requires opa in the authority read's enabledModules. When the list is missing or lacks opa, the user ctx gets a decide that answers 403 on every non-public operation, whatever the persona; public operations stay reachable as for an anonymous caller. A malformed enabledModules is treated as no authority (401).

2. RBAC binding (src/opa-host-rbac.ts, createOpaHostRbac). Identity RBAC's RBACPolicyEngine plus one user-bound, tenant-tagged binding per CompanyOS persona. opa.loop.execute (admin, founder approver, operations manager) and opa.booking.approve (admin, founder approver) follow the api-application-monolith bindings. The profile capabilities (opa.profile.read/manage/publish) and every capability of the meeting-workspace operations a deployment can install through OpaBuildDeps (opa.meeting_policy.*, opa.meeting_workspace.*, opa.meeting_context.*, opa.meeting_artifact.*, opa.meeting_work_session.*, opa.meeting_outcome.*, opa.meeting_dispatch.*, opa.meeting_share.*, opa.recording.source_bind) go to the OPA personas of the managed-companyos coverage manifest (founder approver, operations manager) and the admin. The manifest gives the other personas no OPA coverage, so they get only the meeting capabilities of their AuthOS built-in role template:

   Persona	Meeting operations allowed
   expert_reviewer	opa.meeting_workspace.get, opa.meeting_artifact.list/get, opa.meeting_artifact.review_decide
   auditor	opa.meeting_workspace.get, opa.meeting_artifact.list/get (read-only)
   frontline_staff	opa.meeting_workspace.get
   ai_operator	none (not an assignable AuthOS role)

   Every other operation answers 403 for these personas, including opa.meeting_work_session.*, policy, context, dispatch and sharing, and unknown roles get no binding at all. The runtime authority port still checks the actor's own grant on each meeting resource. An operation group whose capabilities have no persona grant answers 403 for every persona until its capabilities are mapped in src/opa-host-rbac.ts.

3. Policy decision point (src/opa-host-policy.ts). When createOpaRestHandler(ctxFactory, { rbac }) is given an RBAC port, every request context gets a decide that requires the operation's declared capability for a resolved tenant and workspace actor. Public (policy.auth: 'anonymous') operations pass, unknown operations and missing grants are 403, and a context decide can only narrow the result. Bindings are tenant-scoped like the runtime's authorizeOpaOperation (src/opa-host-tenant-scope.ts): grants tagged, scoped or targeted to another tenant are dropped, and own-tenant tenantId or tenant-scope grants are honored. The runtime authority port still rejects a resource from another workspace (403). Without an RBAC port, createOpaRestHandler is default-deny: a non-anonymous ctx that brings no decide of its own (such as the one createOpaHostSessionContext projects) gets one that answers 403 on every non-public operation. Pair the session projection with { rbac }.

Known scope: the CompanyOS authority read does not return the selected team or sub-workspace, so the host scopes OPA to the active organization's workspace (workspace:<segment(activeOrganizationId)>). The route binds no profile or meeting persistence, so it serves only the operation groups a deployment configures through OpaBuildDeps.

The MCP mount (mountOpaMcp) still takes the caller's toolCtx; it does not use this session projection yet.

Local Commands

• bun run test — smoke tests (3 surface mounts + REST round-trip), session projection, REST default-deny and RBAC tests
• bun run typecheck — TypeScript check
• bun run lint:check — Biome check