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

Thin OPA host: mounts the organization-planning operation registry on REST, GraphQL, and MCP surfaces via the shared contracts-runtime adapters.

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `0.1.6`
- Package path: `packages/apps/organization-planning-host`
- Manifest path: `packages/apps/organization-planning-host/package.json`
- Manifest Git blob: `8373d65d54e7fce6c5a089b3856c8a087ffa2e58`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/app.organization-planning-host](https://lssm.co/docs/packages/app.organization-planning-host/)
- Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/)

This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review.

Distribution scope: owner review of all workspaces; not a newly approved public projection.

- [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/organization-planning-host)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/organization-planning-host/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/organization-planning-host/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.organization-planning-host.txt)

## Package metadata

```json
{
  "layer": "apps",
  "physicalArea": null,
  "primaryArea": "company-and-work",
  "classification": {
    "privateDeclared": true,
    "catalogFamily": null,
    "catalogKind": null,
    "catalogStatus": null,
    "adoptionMode": null,
    "stability": null
  },
  "descriptionOrigin": "package.json",
  "manifestComplete": true,
  "publicationPolicyApplied": false
}
```

Manifest private flag: true — workspace only.

Primary area: [Company, work and service operations](https://lssm.co/docs/areas/company-and-work/)

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/apps/organization-planning-host/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/organization-planning-host/README.md",
  "blobSha": "90f391c9319883b4e6eefc7875d89f99931a1a42",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "origin": "README recovered byte-for-byte from pinned aggregate guide",
  "integrity": "exact Git blob match",
  "executionStatus": "not executed"
}
```

The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations.

# @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

- **Layer**: `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`.

| Variable | Purpose |
| --- | --- |
| `OPA_HOST_AUTHOS_BASE_URL` | Origin (no path) of the CompanyOS API, which serves AuthOS and the authority read. Unset → every caller is anonymous. HTTPS only, except `http://localhost`. A value that is not an exact origin (trailing slash, path, credentials, HTTP on another host) is logged once as `opa_host.invalid_authos_base_url` when the route loads, and every caller is then anonymous; public operations keep working. |
| `OPA_HOST_INSECURE_DEV` | `1` enables the LOCAL-ONLY `x-opa-dev-user`/`-tenant`/`-workspace`/`-roles` headers when no bearer is sent. Ignored when `NODE_ENV=production`; the dev subject still needs a persona in `x-opa-dev-roles`. |

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


## Declared capabilities

This manifest does not declare a capability catalogue. Assess the package using its guide, import map and source.

## Catalogue metadata

```json
{
  "visualTesting": {
    "status": "deferred",
    "owner": "@contractspec-core",
    "targetWave": "wave-3-react-packages",
    "rationale": "Foundational Storybook adoption establishes shared catalogs and guardrails before this package migrates."
  }
}
```

## Canonical imports

Import paths and symbols below are catalogue declarations. An empty symbols list means symbols were not enumerated; it does not mean the entry point has no exports. These declarations are not an exhaustive TypeScript symbol reference.

```json
[]
```

## Declared export entry points

Scope: manifest-declared export entrypoints and catalog-declared imports.

Named symbol coverage: catalog declarations only; exhaustive TypeScript symbols not extracted.

Installation status: not verified.

This workspace does not declare package export paths.

## Package publication metadata

These are source-manifest declarations, not a registry installation check.

```json
{
  "types": null,
  "files": null,
  "publishExports": null
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- [@lssm-tech/integration.authos-better-auth](https://lssm.co/docs/packages/integration.authos-better-auth/): `workspace:*`
- [@lssm-tech/lib.contracts-runtime-server-graphql](https://lssm.co/docs/packages/lib.contracts-runtime-server-graphql/): `workspace:*`
- [@lssm-tech/lib.contracts-runtime-server-mcp](https://lssm.co/docs/packages/lib.contracts-runtime-server-mcp/): `workspace:*`
- [@lssm-tech/lib.contracts-runtime-server-rest](https://lssm.co/docs/packages/lib.contracts-runtime-server-rest/): `workspace:*`
- [@lssm-tech/lib.contracts-spec](https://lssm.co/docs/packages/lib.contracts-spec/): `workspace:*`
- [@lssm-tech/lib.design-system](https://lssm.co/docs/packages/lib.design-system/): `workspace:*`
- [@lssm-tech/lib.identity-rbac](https://lssm.co/docs/packages/lib.identity-rbac/): `workspace:*`
- [@lssm-tech/lib.logger](https://lssm.co/docs/packages/lib.logger/): `workspace:*`
- [@lssm-tech/lib.organization-planning-runtime](https://lssm.co/docs/packages/lib.organization-planning-runtime/): `workspace:*`
- [@lssm-tech/lib.organization-planning-spec](https://lssm.co/docs/packages/lib.organization-planning-spec/): `workspace:*`
- [@lssm-tech/lib.translation-runtime](https://lssm.co/docs/packages/lib.translation-runtime/): `workspace:*`
- [@lssm-tech/module.organization-planning](https://lssm.co/docs/packages/module.organization-planning/): `workspace:*`
- [@lssm-tech/opa-booking-react](https://lssm.co/docs/packages/opa-booking-react/): `workspace:*`
- `@modelcontextprotocol/sdk`: `catalog:ai`
- `@pothos/core`: `catalog:graphql`
- `lucide-react`: `catalog:ui`
- `next`: `catalog:`
- `react`: `catalog:`
- `react-dom`: `catalog:`
- `zod`: `catalog:`

### Peer dependencies

No declarations in the inspected manifest.

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- [@lssm-tech/tool.bun](https://lssm.co/docs/packages/tool.bun/): `workspace:*`
- [@lssm-tech/tool.typescript](https://lssm.co/docs/packages/tool.typescript/): `workspace:*`
- `@types/react`: `catalog:types`
- `@types/react-dom`: `catalog:types`
- `typescript`: `catalog:`

### Peer dependency metadata

```json
{}
```

### Bundled dependencies

```json
null
```

## Package scripts

Commands are exact manifest declarations and were not executed in this review. Script metadata status: complete pinned manifest.

```json
{
  "clean": "rimraf dist .turbo",
  "lint": "bun lint:fix",
  "lint:fix": "node ../../../scripts/biome.cjs check --write .",
  "lint:check": "node ../../../scripts/biome.cjs check .",
  "test": "bun test",
  "typecheck": "tsgo --noEmit"
}
```

## Declared documentation links

No additional documentation links are declared in the inspected catalogue.

## Existing agent-guide projection

```json
{
  "path": "packages/apps/web-landing/public/llms-packages/app.organization-planning-host.txt",
  "route": "/llms/app.organization-planning-host",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.organization-planning-host.txt",
  "blobSha": "90f391c9319883b4e6eefc7875d89f99931a1a42",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "bodyEqualsReadme": true,
  "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt",
  "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf"
}
```