Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 16 additions & 6 deletions apps/docs/docs/workforce/durable-hire.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ The files on this page go in your app's own source tree, under `src/flows/`, whe

A hire writes durable state that belongs to an organization, so the organization has to come from something the framework can trust, not from the request body. Configure [`resolvePrincipal`](../server/authentication.md) on the flow and the action's `orgId` comes from there. An `orgId` in the body is ignored, so a caller can't hire into another organization by naming it in the input.

A hired seat is pinned to that organization, so the host that serves the seat needs the same resolver. The framework default resolver does not name one, and opening the seat answers `404 Unknown flow` even for the person who hired it.
A hired seat is pinned to that organization, and every request to it is checked against the pin. The principal for that check comes from the seat's own `authentication` when it has one, and from the host's otherwise. With neither, every caller counts as the default organization, which never matches the pin, so opening the seat answers `404 Unknown flow` even for the person who hired it. So put the resolver that verified the hire on the seat itself, where you register it, as `registerSeat` [below](#reaching-the-flowstate) does. The seat then answers only callers that resolver accepts. If members should call the seat with their own sign-in, register it with a resolver that verifies them and names the same organization. Don't install it host-wide instead: a host-level resolver applies to every flow the app serves.
Comment thread
jhoffner marked this conversation as resolved.
Resolved

```ts title="src/flows/workforce-admin/authentication.ts"
import type { AuthenticationConfig } from "@flow-state-dev/core/types";
Expand Down Expand Up @@ -89,6 +89,8 @@ import type { FlowInstance, InstanceOwnerPin } from "@flow-state-dev/core/types"
import type { FlowState } from "@flow-state-dev/engine";
import { registerHiredSeat } from "@flow-state-dev/workforce";

import { adminAuthentication } from "./authentication";

let app: FlowState | undefined;

/** Call once, immediately after `createFlowState`. */
Expand All @@ -99,7 +101,14 @@ export function useFlowState(next: FlowState): void {
export function registerSeat(seat: FlowInstance, pin?: InstanceOwnerPin): void {
const state = app;
if (!state) throw new Error("No FlowState to register into.");
registerHiredSeat((instance, owner) => state.register(instance, { pin: owner }), seat, pin);
registerHiredSeat((instance, owner) => state.register(withAdminResolver(instance), { pin: owner }), seat, pin);
}

/** The seat answers the credential that hired it. A kind with its own resolver keeps it. */
function withAdminResolver(seat: FlowInstance): FlowInstance {
const { resolvePrincipal } = adminAuthentication;
if (!resolvePrincipal || seat.authentication?.resolvePrincipal) return seat;
return { ...seat, authentication: { ...seat.authentication, resolvePrincipal } };
}

export function releaseSeat(id: string): boolean {
Expand Down Expand Up @@ -167,7 +176,7 @@ export default workforceAdmin();
| `allowKinds?` | The subset of `kinds` these handlers may mint. |
| `channelBoards?` | Channel board ids. For each one the new seat doesn't declare, the hire's `warning` names it, since rows filed on that board sit pending until something works them. |

The seats these handlers and the `seat-hire` tools hire are always org-visible: every member of the organization can call one, and its roster row, `instructions` included, is readable by a browser in that organization. For a seat only one member can reach, write the hire yourself as in [Hiring a seat only one member can reach](#hiring-a-seat-only-one-member-can-reach).
The seats these handlers and the `seat-hire` tools hire are always org-visible: pinned to the organization and no user, so any caller the seat's resolver places in that organization can call one, and its roster row, `instructions` included, is readable by a browser in that organization. For a seat only one member can reach, write the hire yourself as in [Hiring a seat only one member can reach](#hiring-a-seat-only-one-member-can-reach).

Both handlers take the organization from the principal your `resolvePrincipal` returns for the session, as [above](#the-organization-has-to-come-from-the-credential). A session whose principal names no organization, which includes every session on a flow with no `resolvePrincipal`, belongs to the framework's default organization. That id can't start a seat address, so every hire there is refused before anything is written:

Expand Down Expand Up @@ -360,7 +369,7 @@ The roster is organization-scoped, so that `getOptional` is also the fence. Anot

### Hiring a seat only one member can reach

The hire above is org-visible. Every member of the organization can call the seat, and its row is one a browser in that organization can read. To hire a seat that belongs to one member, change the hire like this, in the handler and in `flow.ts`:
The hire above is org-visible: the seat is pinned to the organization and no user, and its row is one a browser in that organization can read. With `registerSeat` as written, the seat answers any caller holding that organization's admin token. To let members call it with their own sign-in, register it with a resolver that verifies them, as described [above](#the-organization-has-to-come-from-the-credential). To hire a seat that belongs to one member, change the hire like this, in the handler and in `flow.ts`:

- **Stamp the owner on the row.** Pass `ownerUserId` to `toHiredSeatRow`, and keep `owningOrgId`, the organization the hire runs under: that stamp is what lets a reload refuse the row if it is ever read under another organization. `hiredSeatManifest` then pins the record to that user as well as the organization, and registering with that pin is what closes the seat to everyone else.
- **Put the owner in the address.** `seatAddress(orgId, seatId, userId)` returns `<orgId>.~<user>.<seatId>`, so two members can each hire `research` without colliding.
Expand Down Expand Up @@ -413,11 +422,12 @@ Once registered, the seat answers its owner only. Any other member gets `404 Unk

## Calling a hired seat

The seat answers immediately, on the same route as any other flow. Its address carries the organization that hired it:
The seat answers immediately, on the same route as any other flow. Its address carries the organization that hired it. With `registerSeat` as written, it answers any admin token configured for that organization, since each resolves to the same principal the seat is pinned to:

```bash
curl -X POST localhost:3000/api/flows/acme.support.ada/actions/answer \
-H 'content-type: application/json' \
-H "authorization: Bearer $ADMIN_TOKEN" \
-d '{"userId":"you","input":{"note":"is the printer fixed?"}}'
```

Expand All @@ -437,7 +447,7 @@ Anyone outside that pair gets the answer an address your app does not serve woul

For example, Alice hires a user-owned `research` seat while signed in to Acme. Bob, also in Acme, cannot open it. Neither can Alice while she is signed in to Globex. If she wants a research seat there, she hires one in Globex, and it starts empty. If Bob hires his own, his starts empty too. [What a seat saves for a person](#what-a-seat-saves-for-a-person) covers why.

**The check is as strong as the principal your resolver returns.** "Who is asking" is the principal your [`resolvePrincipal`](../server/authentication.md) returns: a user and the organization they are signed in to. Use a resolver that verifies both, and install the same one on the host that serves the seat as on the flow that hires it.
**The check is as strong as the principal your resolver returns.** "Who is asking" is the principal your [`resolvePrincipal`](../server/authentication.md) returns: a user and the organization they are signed in to. Use a resolver that verifies both, and install it on each hired seat as well as on the flow that hires it, as `registerSeat` in [Reaching the `FlowState`](#reaching-the-flowstate) does.

## Reading the roster back at the next start

Expand Down
11 changes: 10 additions & 1 deletion apps/kitchen-sink/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ curl -X POST localhost:3000/api/flows/support.ada/actions/answer \

Adding a seat means adding a folder and restarting; adding a kind means adding a file and re-running `fsdev gen`. There is no second place to edit.

Seats can also be hired while the app is running, which is the other half of the demonstration. `support.ada` and the rest are declared in files. A seat hired over `workforce-admin`'s `hire` action is written to the database instead, addressed with its organization (`acme.support.ada`), and is still there after `pnpm build && pnpm start`.
Seats can also be hired while the app is running, which is the other half of the demonstration. `support.ada` and the rest are declared in files. A seat hired over `workforce-admin`'s `hire` action is written to the database instead, addressed with its organization and the admin user (`acme.~workforce-admin.support.bo`), and is still there after `pnpm build && pnpm start`.

The admin flow is **not registered at all** unless `WORKFORCE_ADMIN_TOKENS` is set, so a default run of this app has no working hire path. It takes `<org>:<token>` pairs, and the organization a hire lands in is the one its token names — never what the request body says:

Expand All @@ -108,6 +108,15 @@ curl -X POST localhost:3000/api/flows/workforce-admin/actions/hire \

Over HTTP rather than through `fsdev run`, because the CLI sends a fixed user and no organization, and this action needs one.

The seat answers any admin token configured for its organization, not only the one that hired it: every such token resolves to the same admin principal, and the seat is pinned to that principal. It belongs to the organization and to the admin user, so its address carries both. Another organization's token gets the `404` an unknown address would, and a request with no token gets `401`:

```bash
curl -X POST localhost:3000/api/flows/acme.~workforce-admin.support.bo/actions/answer \
-H 'content-type: application/json' \
-H "authorization: Bearer dev-token" \
-d '{"userId":"you","input":{"note":"Where is my order?"}}'
```

Restart the app and ask the seat something. The reload runs at startup, before the app serves anything, and reports any seat it could not bring back.

### A seat that hires
Expand Down
36 changes: 35 additions & 1 deletion apps/kitchen-sink/lib/workforce-admin-auth.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@

import { timingSafeEqual } from "node:crypto";
import { extractBearerToken, PrincipalResolutionError } from "@flow-state-dev/engine";
import type { ResolvePrincipalFn } from "@flow-state-dev/core/types";
import type { FlowInstance, ResolvePrincipalFn } from "@flow-state-dev/core/types";

/** The env var holding `<org>:<token>` pairs. */
export const ADMIN_TOKENS_ENV = "WORKFORCE_ADMIN_TOKENS";
Expand Down Expand Up @@ -150,3 +150,37 @@ export function adminPrincipalResolver(): ResolvePrincipalFn | undefined {
return { userId: ADMIN_USER_ID, orgId };
};
}

/**
* A seat hired from a roster row, resolving its callers with the admin
* credential that hired it.
*
* A roster hire pins the seat to the organization and user the admin
* credential resolved, and every request to the seat is checked against that
* pin. So the seat has to resolve its callers the same way. With no resolver
* of its own it falls to the framework default, which names the default
* organization, and the pin refuses even the operator who just hired it.
*
* **On the seat instance, and nowhere wider.** A host-level resolver would put
* every open flow in this app (`chat-agent`, the channels, the file-declared
* seats) behind the admin token. A resolver on the kind would do the same to
* the file-declared seats of that kind, which run unpinned for `devuser`. The
* instance is the one place that covers exactly the pinned seats.
*
* The pin is untouched: this only decides who the caller IS, from the verified
* token. Whether that caller may reach the seat is still the pin's call, so
* another organization's credential is refused as before.
*
* Returned unchanged when no credential is configured — nothing can resolve
* the pinned organization, so the pin refuses everyone — and when the seat's
* kind names a resolver of its own, which is that kind's decision to make.
*/
export function withAdminAuthentication(
seat: FlowInstance,
resolvePrincipal: ResolvePrincipalFn | undefined
): FlowInstance {
if (resolvePrincipal === undefined || seat.authentication?.resolvePrincipal !== undefined) {
return seat;
}
return { ...seat, authentication: { ...seat.authentication, resolvePrincipal } };
}
16 changes: 15 additions & 1 deletion apps/kitchen-sink/lib/workforce-registrar.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,16 @@
import type { FlowInstance, InstanceOwnerPin } from "@flow-state-dev/core/types";
import { registerHiredSeat } from "@flow-state-dev/workforce";

import { adminPrincipalResolver, withAdminAuthentication } from "./workforce-admin-auth";

/**
* The resolver every roster-hired seat answers with — the admin flow's own,
* read from the same env at the same point in the boot, so the seat resolves
* a caller exactly as the hire that pinned it did. `undefined` when no admin
* credential is configured.
*/
const hiredSeatResolver = adminPrincipalResolver();

/**
* **Provenance lives here, not in the installed door.** `fire` may release only
* an address this app registered *from a roster row* (BR-28). Nothing on a
Expand Down Expand Up @@ -119,8 +129,12 @@ export const workforceRegistrar: WorkforceRosterRegistrar = {
// A roster hire with no pin — neither the argument nor the pin the row
// stamped onto the instance — refuses here, before the address is marked.
// App and kind flows do not come through this door, so they stay shared.
//
// Every seat through here is pinned, so it resolves its callers with the
// admin credential: without it the seat hears every request as the
// default organization and its own pin refuses the operator who hired it.
registerHiredSeat(
(seat, pin) => impl.register(seat, { pin }),
(seat, pin) => impl.register(withAdminAuthentication(seat, hiredSeatResolver), { pin }),
flow,
options?.pin ?? flow.ownerPin,
);
Expand Down
Loading
Loading