runas

Summary#

runas (principal) { … } runs the block as that user. Every security rule inside it evaluates against them: row filters bind to them, role rules activate for their roles, and what they may not do is refused.

It exists so you can test the thing that is hardest to test and worst to get wrong — that your rules deny the people they should.

Naming a principal this way works only in test code — a [Test], a [TestFixture] body, or a helper declared in a .test.osy file. Anywhere else runas runs as a declared actor and nothing else ([Actor] — a principal that code may run as); every other operand is a compile error, and that is deliberate — see Why it is test-only below.

Signature#

runas (<principalRow>) {
  … // everything in here acts as that user
}

runas (AuthBootstrap) {
  … // everything in here acts as the platform's ephemeral auth principal
}

runas (new Visitor { Id = "guest-b" }) {
  … // everything in here is ANOTHER BROWSER — the principal stays as it is
}

Description#

Seeing what a user sees#

A row filter like allow read where Owner == user means different rows exist for different people. runas is how you observe that:

[Principal] entity User {
  [Required] string Name;
}

entity Doc {
  User Owner;
  [MaxLength(200)] string Title;
  security { allow read where Owner == user; }
}

The test that observes it, and one detail in it that is not decoration: principal is how a test gets hold of the person it wants to be. A [Test] body outside a runas is an anonymous caller (see Outside the block), so a User.Single(…) written there reads nothing and there is nobody to become. A principal declaration resolves unsecured, like the fixture:

principal Alice => User.Single(u => u.Name == "Alice");
principal Bob   => User.Single(u => u.Name == "Bob");

[TestFixture]
void Seed() {
  var alice = new User { Name = "Alice" };
  var bob = new User { Name = "Bob" };
  var aliceDoc = new Doc { Owner = alice, Title = "alice-doc" };
  var bobDoc = new Doc { Owner = bob, Title = "bob-doc" };
}

[Test(Seed)]
void A_user_sees_only_their_own_docs() {
  runas(Alice) {
    Assert.Equal(1, Doc.Count());                          // Bob's row is not merely hidden — it does not exist for her
    Assert.Equal("alice-doc", Doc.Single(d => true).Title);
  }
}

Read that first assertion carefully. Under runas(Alice), Doc.Count() is 1. The filter is not a mask applied after the fact; it is part of the query. Bob's row is not in the result set to be filtered out — it was never in it.

Proving the denial#

Pair runas with Assert.Denied to claim that someone is refused:

[Test(Seed)]
void Bob_cannot_read_Alices_doc() {
  runas(Bob) {
    Assert.Equal(0, Doc.Count(d => d.Owner == Alice));   // Alice's doc is not his to see
  }
}

Outside the block — the fixture is unrestricted, the test body is NOBODY#

These are two different things, and reading them as one is a half-hour lost:

• A [TestFixture] runs unsecured, so it can seed rows across every entity without fighting the rules it is about to test.
• A [Test] body outside a runas block runs as an anonymous caller — secured, with no principal. Under deny-by-default a read there returns nothing, which is why a Assert.NotNull on it fails rather than passing on unrestricted access.

Until something signs you in. Driving the app's own sign-in — Ui.SignInAs(Alice), or filling and submitting its login form — makes the test body that person for the rest of the test, exactly as it makes the browser that person. Reads after it are Alice's reads and need no runas wrapper; reads written above it are still nobody's. Ui.SignOut() takes it away again.

That asymmetry is deliberate, and it is worth stating plainly: security is only tested inside runas, or as somebody you signed in. A test that does neither has tested what nobody can do.

A row carried out of the block is read again by whoever the test is now. Assign a row to a variable inside runas (Alice) { … } and read it after the block, and it is read as the test body — nobody — exactly as it would be for them in the app. When nobody may read it (or that field of it), the read stops the test and says so: "….Subject reads as null here because this row was read inside runas (Alice) and is used after that block ended…". Make the assertion inside the block, or copy the values you need into a variable or a class before it ends. Carrying a row into another runas block is different and is answered as before: that principal is served only what they may read.

Seeding as somebody — runas in a fixture#

A fixture writes unsecured, but some of what it seeds goes through the app's own functions, and those may ask who is acting — an [Authorize] function, or one that reads Session.CurrentUser. Write the runas straight in the fixture's body: the person it names is bound for the block (their roles too), exactly as in a test. What the fixture writes still writes past security { }; runas only says who the app's code is acting for.

principal Carol => User.Single(u => u.Name == "Carol");

// An ordinary function that files a doc for whoever is acting — so it needs SOMEBODY to be acting.
void FileForWhoeverIsActing(string title) {
  new Doc { Owner = User.Single(u => u.Id == Session.CurrentUser!.Id), Title = title };
}

[TestFixture]
void CarolsDesk() {
  new User { Name = "Carol" };
  runas (Carol) { FileForWhoeverIsActing("carol-doc"); }
}

[Test(CarolsDesk)]
void The_fixture_filed_it_as_Carol() {
  runas (Carol) { Assert.Equal("carol-doc", Doc.Single(d => true).Title); }
}

Does a helper need its own runas?#

No — the acting principal flows down the whole call chain. runas rebinds who is asking for the rest of the block, calls it makes included, so an ordinary function has nothing extra to do: it inherits whoever is running it.

// AN ORDINARY FUNCTION — not [Test], not [TestFixture], and no runas of its own (writing one here hits the compile
// error below in an app file). It needs none: whoever the CALLER's runas bound is still bound
// while this statement runs.
Doc FindMyDoc(string title) => Doc.FirstOrDefault(d => d.Title == title);

[Test(Seed)]
void A_helper_acts_as_whoever_called_it() {
  runas(Alice) {
    Assert.NotNull(FindMyDoc("alice-doc"));   // her own row filter is evaluated as HER, from inside the helper
  }
  runas(Bob) {
    Assert.Null(FindMyDoc("alice-doc"));      // the SAME helper, called as Bob, sees nothing — RLS still applies
  }
}

So a shared helper is written once, with no principal ceremony of its own, and the test switches who is acting between calls:

runas(Mia)  { Found(); Invite(); }   // Mia founds the org and sends the invite
runas(Otto) { Accept(); }            // Otto — a DIFFERENT principal — accepts it

Found, Invite and Accept each run as whoever called them; none needs a runas of its own, and a helper declared in a .test.osy file MAY declare one ("as staff, approve this"), since everything in a test file is test code — but the same helper in an app file is refused (see Why it is test-only below). A helper that itself needs to act as TWO people within one call is the wrong shape: split it, and let the caller switch between calls instead, exactly as above.

Reading a credential, as the auth flow#

runas (AuthBootstrap) is the one form whose argument is not a row. It becomes the same user-less ephemeral principal the platform arms an [AuthMethod] with: no current user, bearing the [Role] your app.AuthBootstrap declares, with exactly that role's ordinary security {} grants and nothing more.

It exists because a properly-masked credential has exactly one legitimate reader, and until this form a test could not be it:

security {
  deny read PasswordHash when !IsAuthenticator;   // the shape every app is told to write
  deny read ResetToken   when !IsAuthenticator;
}

That mask makes the field unreadable to every principal a test can name — which is correct, and which left a test needing to observe what the auth flow observes with nowhere to stand. The practical result was worse than the gap: an app whose reset flow had to be tested simply left the token unmasked, and an unmasked credential on the [Principal] rides to the browser on the Session.CurrentUser payload.

// what the email carried — read as the only thing allowed to see it
string token = "";
runas (AuthBootstrap) { token = User.Single(u => u.Email == "[email protected]").ResetToken; }

⛔ This peek stands in for the mailbox, and it is honest only if there IS one. Over an app whose reset flow really mails the token, reading the column as the auth principal is a fair substitute for opening the mail. Over an app that mints a token and sends nothing, the identical two lines are a back door: the test completes a flow no user could, and reports that the flow works. That is not a hypothetical — demo/auth-demo shipped exactly that, with four green tests over it, until 2026-09-04. So pair this peek with something that asserts the token actually LEFT (the provider's message id on the row, say); security-reset-token-never-delivered (MUST) catches the app-shaped half.

It grants no new authority. It is the arming the platform already performs for Login, Signup and PasswordReset, reachable from a test — so what it can read is what your own auth flow can read, decided entirely by the grants you wrote. It stays test-only like every other runas, and it fails loudly rather than quietly running anonymously if the app declares no app.AuthBootstrap — because a block that reads a masked field while bound to nobody reads null, and an assertion over that would pass for the wrong reason.

Being another browser#

A guest's rows are their own VISIT's (guest rows (a visit's own rows)), and a test is one browser — a fresh visitor, whose Ui.* screen is handed the same one. runas (new Visitor { Id = "…" }) makes a block a different browser. Only the visitor changes: signed in or not stays as it was, so nesting a principal inside it is "that person, on that browser", and Ui.* verbs inside it drive a screen that is that visitor too. A return inside any runas block returns from the function, so a helper can answer as a visitor:

int BasketsOf(string visit) {
  runas (new Visitor { Id = visit }) { return Basket.Count(); }
}

Why it is test-only#

runas rebinds the acting user and that user's roles. Inside the block, every rule you wrote evaluates for somebody else. That is exactly what a security test needs and exactly what application code must never be able to do: it would let any code become any user it could merely look up, and on the ordinary shape where signed-in users can read the user directory, that is everybody.

The platform's promise is that you decide security once, on the entity, and it then holds everywhere without you checking — you never have to ask whether a particular read, function or screen honours it. That promise only survives while nothing in the language can step around it. So the compiler refuses runas to a principal outside test code, and the runtime refuses it again in any run a test or fixture did not start:

`runas(...)` is a TEST-ONLY construct and this is not test code (a [Test], a [TestFixture], or a helper in a
`.test.osy` file). It rebinds the acting principal and that principal's roles, which bypasses the security you
declared on your entities — so app code may not speak it.

If a job needs an identity of its own — a nightly run, a machine, an assistant — declare it: a class marked [Actor] is the one thing code outside a test may run as, with the roles its declaration names and no others ([Actor] — a principal that code may run as). A test may run as one too: runas (BillingRobot) { … } means the same in both.

If you need authority before anyone is signed in — a login, a signup, an OAuth callback, which must read or write user rows with no user yet — that is auth bootstrap (login, before anyone is signed in), not this. You declare a role and a policy that leashes it, mark the entry points [[security-auth-method|[AuthMethod]]], and the platform runs them as an ephemeral principal bearing that role. The elevation is declared in one place a reviewer can find, bounded by a predicate, and still not something app code can grant itself.

See also#

• Assert — Assert.Denied, the assertion runas makes possible
• secure by default (deny-all) — what is denied before you write any rule
• principal predicates (IsAuthenticated / IsAnonymous / IsTheApp) and open reads — the user a rule compares against