runas

Runs a block as a given principal, so security rules apply exactly as they would for that user. It is how you test that a rule denies the people it should — the only way to prove security from inside the app. It is TEST-ONLY: a `runas` outside a `[Test]` is a compile error, because app code may not step outside the security it declared.

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.

It works only inside a [Test]. Writing runas anywhere else 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
}

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.

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 above: this is not a [Test] function). 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 none could declare one — that stays refused outside a [Test] body (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.

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 outside a [Test]:

`runas(...)` is a TEST-ONLY construct and this is not a [Test] function. 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 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.