# Checking what a workflow's actor would be refused — osy validate --runs-as

> `osy validate --runs-as` is a read-only report for the move from "a workflow body runs as the system" to "a workflow declares who it runs as". For each workflow, `[On]` handler and `[OnStart]` hook it names the actor the body runs as — the declared `RunsAs`, or a proposed actor that holds no role when there is none — and every write or `[Authorize]` call, through the functions the body calls, that actor's roles would be refused. Each row is a grant you owe the actor, or a line to look at by hand. It changes nothing and is not an error.

<!-- id: local-checking-runs-as · area: local · stability: preview · html: https://osysharp.com/reference/local/checking-runs-as/ -->

## Summary        {#summary}
A workflow that declares `RunsAs = BillingRobot;` answers to what `BillingRobot` may do under your `security { }` rules
([Who a workflow body runs as — and what it may write](https://osysharp.com/reference/workflow/body-security/)). Before you name the actor you want to know what it will be refused; after, whether the roles
you gave it are enough. `osy validate --runs-as` answers both from the compiled model, and the answer is the security
engine's own: the model is loaded for a caller who holds the actor's roles, and every write the body can make is put to
the same check a request would be.

```console
$ cd demo/release-canary && osy validate --runs-as
start-hook EnsureCanaryAccount runs as proposed EnsureCanaryAccountActor (no role): 2 write/authorize site(s), 2 refused, 0 maybe
    refused create Osysharp.Identity.RoleGrant.Member,Role  (line 43) — Create of 'Osysharp.Identity.RoleGrant' denied — no `create` rule is active for this caller. It grants `create` under: `IsAuthenticator`. …
    refused create Osysharp.UserAccounts.User.Email,DisplayName,PasswordHash,EmailVerifiedAt  (line 41) — Create of 'Osysharp.UserAccounts.User' denied — `deny create when !IsAuthenticator`, … 
workflow CanaryFlow runs as proposed CanaryFlowActor (no role): 1 write/authorize site(s), 0 refused, 0 maybe
runs-as: 1 workflows, 0 handlers, 2 start hooks; 5 refused writes, 0 maybes; 7 workflows from used packages not counted (report on the package)
```

## Signature      {#signature}
```console
osy validate --runs-as           # the report as text, one block per workflow, handler and start hook
osy validate --runs-as --json    # { items: [{ kind, name, package, actor, proposed, roles, writes, rows: [{ verdict, kind, entity, fields, via, why, line }] }], workflowsFromOtherPackages }
```
Exit code: `0` the report was made, whatever it says · `1` the project does not validate and compile (fix what `osy validate`
reports first, then ask again).

## Description    {#description}

### What is reported?   {#what}
One item per **workflow**, per **`[On]` handler** and per **`[OnStart]` hook** of the project. Its heading line says who the
body runs as and how many write or `[Authorize]` sites it reaches:

| the heading says | meaning |
|---|---|
| `runs as BillingRobot [Billing]` | the declared `RunsAs`, and the roles its declaration names |
| `runs as proposed XActor (no role)` | nothing is declared (also for a handler or hook that names none), so the report takes an actor that holds **no role**: every `refused` row is a grant the move owes it |
| `runs as System []` | `RunsAs = System;`: the body is not judged as anyone, so no rows are listed |

Under it, a row per distinct site — one entity, its fields and the operation, collapsed over the functions the body calls
(`via`, with the line):

| verdict | meaning |
|---|---|
| `refused` | the actor's roles would be refused here. The `why` is the refusal the security engine gives, which says what to grant |
| `maybe` | the report cannot decide: the grant holds only over some rows (a `where`), the call carries `[Authorize(SomePolicy)]` (a policy is not evaluated), or the call cannot be followed (a `virtual` or unresolved one) |

A write inside `runas (Other) { … }` is the other actor's and is not listed as a refusal of the body. A kit's own workflow is
judged with the kit's plain denies waived, as it runs ([[workflow-body-security#kit-deny]]). The last line sums the project;
workflows that belong to a package the project `use`s are counted there, not listed — run the report on the package.

### How do I use it?   {#use}
1. Run it on an app that has no `RunsAs` yet. The proposed actor holds no role, so the list is everything the bodies write.
2. Declare the actor with the narrowest roles that make sense ([[Actor] — a principal that code may run as](https://osysharp.com/reference/security/declared-actor/)), or grant by identity —
   `allow create when user == Actor.Of<BillingRobot>()` — for a row only that actor writes.
3. Name it in the workflow, and run the report again. What is still `refused` is a body that does something its author did
   not mean it to; `maybe` rows are read by hand.
4. A body that names a member its actor cannot read is warned separately (`WORKFLOW_ACTOR_READS_A_HIDDEN_MEMBER`,
   [[security-declared-actor#hidden-reads]]), and a workflow with no `RunsAs` in an app that has a `[Principal]` carries
   `WORKFLOW_RUNS_AS_THE_SYSTEM` ([[workflow-body-security#system]]).

### What it does not see   {#limits}
- Roles only: a rule the roles pass but that also asks the data (`where Owner == user`) is `maybe`.
- It does not run anything. A write reached through a call it cannot follow, or one decided by a value, may be missing or
  listed as `maybe`.

## See also       {#see-also}
- [Who a workflow body runs as — and what it may write](https://osysharp.com/reference/workflow/body-security/) — who a workflow body runs as
- [[Actor] — a principal that code may run as](https://osysharp.com/reference/security/declared-actor/) — declaring the actor and granting it
- [Checking every project at once — osy validate --all / --affected](https://osysharp.com/reference/local/checking-every-project/) — `osy validate --all`, the same check over every project
- [Checking your app](https://osysharp.com/reference/local/checking-your-app/) — `osy validate` for one project
