@cratis/pi 0.0.1

package/skills/cratis-arc-authentication-authorization-and-identity/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: cratis-arc-authentication-authorization-and-identity
+description: Wire authentication, authorization and identity in a Cratis Arc application — IProvideIdentityDetails and the /.cratis/me endpoint, the [Authorize]/[Roles]/[AllowAnonymous] attributes Arc actually evaluates, IAuthenticationHandler, the Microsoft Identity Platform header contract, tenant resolution, and the React identity hooks. Use for Arc identity providers, endpoint protection, roles, or frontend identity integration. Do not use for isolated command validation, and do not use for Chronicle tenant namespaces alone.
+license: MIT
+---
+
+# Authentication, authorization and identity in Arc
+
+Arc separates three things that are easy to conflate: **authentication** decides
+who the caller is, **authorization** decides whether that caller may run this
+command or query, and the **identity provider** decides what the frontend is
+told about them. Each has its own extension point.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Arc.Core` | `22.10.4` | `Cratis.Arc.Identity`, `Cratis.Arc.Authorization`, `Cratis.Arc.Authentication`, `Cratis.Arc.Tenancy` |
+| `Cratis.Arc` | `22.10.4` | ASP.NET Core hosting, `AddMicrosoftIdentityPlatformIdentityAuthentication` |
+| `@cratis/arc` | `22.10.4` | `IdentityProvider`, `IIdentity` |
+| `@cratis/arc.react` | `22.10.4` | `IdentityProvider` component, `useIdentity`, `RequireRole` |
+
+Reverify before claiming support for another version.
+
+## Read this first: what is and is not trusted
+
+Arc's shipped authentication reads a **forwarded** principal from HTTP headers.
+`x-ms-client-principal` is base64, **not a signature**, and Arc does not check
+who sent it. Any caller that can reach the application can author the entire
+serialized principal.
+
+That is not a defect — it is the EasyAuth/reverse-proxy model, where the ingress
+is the trust boundary. But it means:
+
+- the application must be unreachable except through the ingress that sets those
+  headers;
+- nothing Arc gives you makes the forwarded values authentic;
+- Arc ships **no** OpenID Connect and **no** JWT bearer integration. If you need
+  the application itself to validate a token, that is ordinary ASP.NET Core
+  authentication you configure yourself.
+
+## Identity details — what the frontend is told
+
+Implement `IProvideIdentityDetails` to shape what `/.cratis/me` returns:
+
+```csharp
+using Cratis.Arc.Identity;
+
+public class <Name>IdentityDetailsProvider : IProvideIdentityDetails<<Details>>
+{
+    public async Task<IdentityDetails> Provide(IdentityProviderContext context)
+    {
+        // context.Id, context.Name, context.Claims
+        return new IdentityDetails(<isAuthorized>, new <Details>(<...>));
+    }
+}
+```
+
+- `IdentityDetails` is `record IdentityDetails(bool IsUserAuthorized, object Details)`.
+  `Details` is **`object`**, not generic; it is serialized as JSON.
+- `IProvideIdentityDetails<TDetails>` adds no members. It exists only so Arc can
+  capture the details type reflectively, which is what feeds the JSON schema
+  endpoint and the generated proxy. Implement **both** — the generic one for the
+  type, the non-generic `Provide` for the behavior.
+- `IdentityProviderContext` is `(IdentityId Id, IdentityName Name, IEnumerable<KeyValuePair<string, string>> Claims)`.
+- Registration is by discovery: exactly one non-default implementation is
+  expected. More than one is `MultipleIdentityDetailsProvidersFound`; none falls
+  back to `DefaultIdentityDetailsProvider`, which returns
+  `new IdentityDetails(true, new { })`. The provider is registered **scoped**.
+
+### The endpoints
+
+| Route | What it does |
+| --- | --- |
+| `GET /.cratis/me` | The current identity. 401 when not authenticated, 403 when the provider says not authorized, otherwise the result plus the identity cookie |
+| `GET /.cratis/identity-details/schema` | The JSON schema of the details type |
+| `GET /.cratis/users` | Development tooling — aggregates every `ICanProvideUsers` |
+| `GET /.cratis/tenants` | Development tooling — aggregates every `ICanProvideTenants` |
+
+All four are mapped `AllowAnonymous`; `/.cratis/me` does its own 401/403. There
+is no public constant for these routes — they are string literals in the endpoint
+mapper.
+
+`/.cratis/me` writes the result as JSON **and** as a base64 cookie named
+`.cratis-identity`, deliberately **not `HttpOnly`** so the frontend can read it
+without a round trip. `Secure` follows whether the request is HTTPS, `SameSite`
+is `Lax`, `Path` is `/`.
+
+⚠️ A non-`HttpOnly` cookie the browser can read is a cookie the user can edit.
+Treat everything in it as a **display** input. Never let it decide anything the
+server has not already decided.
+
+## Authorization — what Arc actually evaluates
+
+Arc ships exactly three attributes, all in `Cratis.Arc.Authorization`:
+
+| Attribute | Targets | Notes |
+| --- | --- | --- |
+| `[AllowAnonymous]` | class, method | No arguments |
+| `[Authorize]` | class, method, repeatable | Settable `Policy`, `Roles` (comma-delimited), `AuthenticationSchemes` |
+| `[Roles(params string[] roles)]` | class, method | Derives from `[Authorize]`, joins the roles with commas |
+
+There is **no** `[Policy]`, `[Scopes]` or `[Claims]` attribute anywhere in Arc.
+
+⚠️ **`AuthorizeAttribute.Policy` and `AuthenticationSchemes` are declared but
+never read by Arc's evaluator.** Writing `[Authorize(Policy = "…")]` compiles and
+enforces nothing. Only `Roles` is evaluated.
+
+Evaluation, in order:
+
+1. every `IAnonymousEvaluator` is consulted; the first non-null answer decides
+   anonymous access;
+2. every `IAuthorizationAttributeEvaluator` is consulted for `[Authorize]` and
+   its `Roles`;
+3. no `[Authorize]` at all means **authorized**; with `[Authorize]`, a null or
+   unauthenticated principal fails, and a non-empty role list passes when the
+   user is in **any** of them (comma-split and trimmed — OR, not AND);
+4. a method with no `[Authorize]` falls back to its declaring type's verdict.
+
+Both `[Authorize]` and `[AllowAnonymous]` on the same member throws
+`AmbiguousAuthorizationLevel`.
+
+`ARC0011` warns when a `[Roles]` argument is a string literal: use
+`nameof(<RoleEnum>.<Member>)` so a rename is a compile error rather than a silent
+authorization failure — a desynchronized literal either locks the endpoint or
+matches a stale role.
+
+Read [authorization](references/authorization.md) for the default-access
+question, which is genuinely different between Arc's two hosting models, and for
+the filter and system-execution extension points.
+
+## Authentication — the extension point
+
+`IAuthenticationHandler` is a single method,
+`Task<AuthenticationResult> HandleAuthentication(IHttpRequestContext context)`.
+Implement it and it is discovered — there is **no** `IArcBuilder` extension and
+**no** options type for authentication.
+
+`AuthenticationResult` is
+`record (ClaimsPrincipal? Principal = default, AuthenticationFailure? Failure = default)`
+with `Anonymous`, `Succeeded(principal)` and `Failed(reason)`, and
+`IsAuthenticated => Principal is not null`.
+
+Arc ships `MicrosoftIdentityPlatformAuthenticationHandler` in `Arc.Core`, which
+reads the forwarded principal. See
+[authentication](references/authentication.md) for the exact header contract,
+the claim Arc reserves, and the ASP.NET Core scheme variant.
+
+## Tenancy
+
+`Cratis.Arc.Tenancy` resolves a tenant per request. The default resolver is
+**header-based** on `x-cratis-tenant-id`; `TenantResolverType` also offers
+`Query`, `Claim`, `Development`, `Subdomain` and `Fixed`, configured through
+`ArcOptions.Tenancy` or the `Use*Tenancy` extension methods.
+
+`ITenantIdAccessor.Current` gives the current `TenantId`, which is
+`TenantId.NotSet` (`"[NotSet]"`) when nothing resolved. See
+[tenancy](references/tenancy.md) for the exact defaults and each resolver's
+behavior.
+
+Arc tenancy is request-scoped tenant *resolution*. It is not Chronicle's tenant
+namespace isolation — that is separate guidance.
+
+## Frontend
+
+```tsx
+import { Arc } from '@cratis/arc.react';
+
+<Arc detailsType={<Details>}>{children}</Arc>
+```
+
+`<Arc>` renders the `IdentityProvider` context for you. Inside it:
+
+```tsx
+import { useIdentity, RequireRole } from '@cratis/arc.react/identity';
+
+const identity = useIdentity(<Details>, <defaultDetails>);
+// identity.id, .name, .roles, .details, .isSet, .isInRole(role)
+// identity.isLoading, identity.clearIdentity()
+```
+
+`useIdentity` has two overloads: `(type, defaultDetails?)` for type-safe details
+and `(defaultDetails?)` without. The default details stand in whenever there are
+no details to give, not only when the identity is explicitly unset.
+
+`RequireRole` gates rendering by `roles` or by an `allow` predicate, with
+`whileLoading` and `forbidden` slots.
+
+⚠️ **`RequireRole` hides UI; it does not protect data.** The identity it reads
+comes from the deliberately non-`HttpOnly` cookie above. Every rule it expresses
+must also exist on the server as `[Authorize]`/`[Roles]` or an authorization
+filter.
+
+`Arc.React.MVVM` has **no** identity hook. It registers `IIdentityProvider` in
+its container so a view model can constructor-inject it; that is all.
+
+See [frontend](references/frontend.md) for the exact exported shapes.
+
+## Local development
+
+Arc ships **no** development identity provider, no fake principal, and no local
+sign-in. What exists for development is the two anonymous listing endpoints,
+`/.cratis/users` and `/.cratis/tenants`, which aggregate whatever the application
+implements as `ICanProvideUsers` and `ICanProvideTenants`.
+
+To run locally with an identity, supply the forwarded headers yourself — see
+[local development](references/local-development.md).
+
+⚠️ Those two endpoints are `AllowAnonymous` and mapped unconditionally. If your
+`ICanProvideUsers` implementation returns real users, that list is public. Return
+development fixtures only, and gate the implementation on a development
+environment check.
+
+## Verify
+
+- Exactly one non-default `IProvideIdentityDetails` implementation exists, and it
+  also implements `IProvideIdentityDetails<TDetails>`.
+- No authorization decision depends on `[Authorize(Policy = …)]`.
+- `[Roles]` arguments use `nameof`, so `ARC0011` is silent.
+- No member carries both `[Authorize]` and `[AllowAnonymous]`.
+- Every rule the frontend enforces also exists on the server.
+- Nothing trusts the identity cookie or the forwarded headers beyond what the
+  ingress guarantees.
+- The application is not reachable except through that ingress.
+- Development user and tenant providers return fixtures, never production data.
+- `dotnet build` is clean in Debug and Release.
+
+## Route near misses
+
+- Rejecting a command's input or state: `cratis-arc-command-validation` scope.
+- Chronicle tenant namespaces and per-tenant event stores: the Chronicle
+  multi-tenancy guidance.
+- Building the React page that consumes identity: the Arc React guidance.

package/skills/cratis-arc-authentication-authorization-and-identity/references/authentication.md

@@ -0,0 +1,140 @@
+# Authentication
+
+Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.10.4`. Types are in
+`Cratis.Arc.Authentication` and `Cratis.Arc.Identity`.
+
+## The contract
+
+```csharp
+public interface IAuthenticationHandler
+{
+    Task<AuthenticationResult> HandleAuthentication(IHttpRequestContext context);
+}
+```
+
+`IAuthentication` aggregates the discovered handlers: `HasHandlers`, and a
+`HandleAuthentication` that returns the **first** result which is either
+authenticated or carries a failure; otherwise `AuthenticationResult.Anonymous`.
+
+```csharp
+public record AuthenticationResult(
+    ClaimsPrincipal? Principal = default,
+    AuthenticationFailure? Failure = default)
+{
+    public static readonly AuthenticationResult Anonymous;
+    public bool IsAuthenticated => Principal is not null;
+    public static AuthenticationResult Failed(AuthenticationFailureReason reason);
+    public static AuthenticationResult Succeeded(ClaimsPrincipal principal);
+}
+```
+
+`AuthenticationFailure` is `record (AuthenticationFailureReason Reason)` and
+`AuthenticationFailureReason` is a `ConceptAs<string>` with an implicit string
+conversion.
+
+There is **no** `IArcBuilder` extension and **no** options type for
+authentication. Configuration is by discovery — implement the interface on a
+public class and it is registered through the convention bindings.
+
+## The Microsoft Identity Platform handler
+
+`MicrosoftIdentityPlatformAuthenticationHandler` ships in **Arc.Core** and is
+transport-agnostic. (Documentation that says it exists only in the ASP.NET Core
+package and must be hand-written for Arc.Core is stale.)
+
+It reads three headers, all constants on
+`Cratis.Arc.Identity.MicrosoftIdentityPlatformHeaders`:
+
+| Constant | Header |
+| --- | --- |
+| `PrincipalHeader` | `x-ms-client-principal` |
+| `IdentityIdHeader` | `x-ms-client-principal-id` |
+| `IdentityNameHeader` | `x-ms-client-principal-name` |
+
+All three must be present or the result is `Anonymous`. The principal header is
+base64-decoded and deserialized into `ClientPrincipal`:
+
+```csharp
+public class ClientPrincipal
+{
+    public string IdentityProvider { get; set; }
+    public string UserId { get; set; }
+    public string UserDetails { get; set; }
+    public IEnumerable<string> UserRoles { get; set; }
+    public IEnumerable<ClientPrincipalClaim> Claims { get; set; }
+}
+
+public class ClientPrincipalClaim
+{
+    public string typ { get; set; }
+    public string val { get; set; }
+}
+```
+
+The lowercase `typ`/`val` members are the deliberate wire shape — do not
+"correct" them.
+
+A principal that fails to decode produces
+`AuthenticationResult.Failed("Not authenticated - invalid representation of ClientPrincipal")`.
+
+From a valid principal the handler builds a `ClaimsIdentity` whose
+authentication type is `nameof(MicrosoftIdentityPlatformAuthenticationHandler)`:
+
+1. every forwarded claim is copied as `Claim(typ, val)`;
+2. `NameIdentifier`, `sub`, and any existing
+   `urn:cratis:arc:identity:provider` claim are **removed** (the last one
+   case-insensitively);
+3. `Name` is set from `UserDetails`;
+4. `NameIdentifier` and `sub` are set from the `x-ms-client-principal-id` header
+   — not from the body;
+5. `urn:cratis:arc:identity:provider` is written from `IdentityProvider` when it
+   is not blank;
+6. every entry of `UserRoles` becomes a `Role` claim.
+
+## The reserved claim
+
+`MicrosoftIdentityPlatformClaims.IdentityProvider` is
+`"urn:cratis:arc:identity:provider"`. Removing any inbound claim of that type
+before writing Arc's own buys **single provenance, not authenticity**: the claim
+carries exactly one value, always from the same field of the forwarded principal.
+
+Read it with `ClaimsPrincipal.FindFirst`/`FindAll` and never normalize the claim
+type yourself. Those lookups compare the way the removal does; folding types with
+`ToUpperInvariant` or `Trim` widens the match beyond what was removed, so a
+forged type differing only by Unicode case folding or trailing whitespace would
+match — and it precedes Arc's claim in the list.
+
+The value's meaning is the ingress's choice, not Arc's: one ingress forwards a
+canonical provider key, another an authentication scheme name or a display name
+that changes when the provider is renamed. Treat it as metadata for telling
+federations apart and for diagnostics. Where a durable provider key is needed,
+read the claim the ingress publishes for that purpose.
+
+Claim types outside the reserved set are copied through untouched.
+
+## ASP.NET Core hosting
+
+```csharp
+services.AddMicrosoftIdentityPlatformIdentityAuthentication(scheme?);
+```
+
+registers the standard ASP.NET Core scheme backed by
+`MicrosoftIDentityPlatformAuthHandler` (note the capital `D` in the type name),
+whose `SchemeName` is `"MicrosoftIdentityPlatform"`. `builder.AddCratis()` calls
+this for you.
+
+## What is not here
+
+There is **no** OpenID Connect, **no** JWT bearer, and **no**
+`Microsoft.Identity.Web` anywhere in Arc — neither in source nor in the shipped
+documentation. Validating a token inside the application is ordinary ASP.NET
+Core authentication that you configure yourself; Arc's model is a trusted ingress
+forwarding a principal.
+
+## The security boundary, stated plainly
+
+`x-ms-client-principal` is base64, not a signature, and Arc does not check who
+sent it. Any caller that can reach the application can author the entire
+serialized principal, including the fields Arc reads. Trust it exactly as far as
+you trust that your ingress is the only thing that can set it — which means the
+application must not be reachable any other way.

package/skills/cratis-arc-authentication-authorization-and-identity/references/authorization.md

@@ -0,0 +1,112 @@
+# Authorization
+
+Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.10.4`. Everything below
+is in `Cratis.Arc.Authorization` unless stated.
+
+## Default access differs by hosting model
+
+There is **no option anywhere in Arc** that sets a default authentication or
+authorization requirement. `ArcOptions` has no such switch. What you get depends
+on which pipeline is running.
+
+### Self-hosted `ArcApplication` (Arc.Core)
+
+`AuthenticationMiddleware` runs per request:
+
+- **No `IAuthenticationHandler` registered at all → every endpoint is anonymous.**
+  The middleware returns immediately.
+- With at least one handler registered, an endpoint marked `AllowAnonymous`
+  passes and everything else requires an authenticated principal — otherwise the
+  response is **401** with a body of `Unauthorized`.
+
+`AllowsAnonymousAccess` defaults to **false**: `IsAnonymousAllowed()` on a
+top-level type with no attributes has no declaring type to fall back to and
+returns false. So under this pipeline commands and queries are
+authenticated-by-default *once any handler exists*.
+
+### ASP.NET Core hosting (the `Arc` package)
+
+The endpoint mapper only ever calls `AllowAnonymous()`. It **never** calls
+`RequireAuthorization()`, and nothing else in Arc does either. Endpoints are
+therefore **anonymous by default** unless the application configures its own
+fallback policy in ASP.NET Core.
+
+Decide this deliberately for your host. Do not assume "Arc protects it".
+
+## Role evaluation
+
+`AuthorizationEvaluator`:
+
+1. every `IAnonymousEvaluator` is asked; the first non-null answer wins — `true`
+   authorizes immediately, `false` stops asking and moves on;
+2. every `IAuthorizationAttributeEvaluator` is asked for `[Authorize]` and its
+   `Roles`; the first that reports one wins;
+3. no `[Authorize]` → **authorized**;
+4. `[Authorize]` with a null or unauthenticated principal → denied;
+5. `[Authorize]` with roles → authorized when the user is in **any** of them.
+   The string is comma-split and trimmed. It is OR, never AND;
+6. a `MethodInfo` with no `[Authorize]` falls back to its declaring type.
+
+`[Authorize]` and `[AllowAnonymous]` on the same member throws
+`AmbiguousAuthorizationLevel` from `AnonymousEvaluator` and from
+`AllowAnonymousExtensions.IsAnonymousAllowed`.
+
+⚠️ The ASP.NET Core-flavoured evaluators (`AspNetAnonymousEvaluator`,
+`AspNetAuthorizationAttributeEvaluator`) are declared inside
+`namespace Cratis.Arc.Authorization` and do not import
+`Microsoft.AspNetCore.Authorization`, so the attribute names in them bind to
+**Arc's own** attributes. Do not rely on ASP.NET Core's `[Authorize]` being
+honoured by them. `AspNetAnonymousEvaluator` also does not throw on the
+both-attributes case; it prefers `AllowAnonymous`.
+
+## The filters
+
+| Interface | Namespace | Shape |
+| --- | --- | --- |
+| `IAuthorizationCommandFilter` | `Cratis.Arc.Commands` | Empty marker over `ICommandFilter` (`Task<CommandResult> OnExecution(CommandContext)`) |
+| `IAuthorizationQueryFilter` | `Cratis.Arc.Queries` | Empty marker over `IQueryFilter` (`Task<QueryResult> OnPerform(QueryContext)`) |
+
+Both are found by discovery — implement one on a public class and it is picked
+up. The marker is what guarantees ordering: the filter chains sort
+authorization filters first with a stable sort, so a validation failure can never
+short-circuit the chain before the authorization verdict is recorded.
+
+Built-in implementations: the command `AuthorizationFilter` returns
+`CommandResult.Unauthorized(...)` from `IAuthorizationEvaluator`; the query
+`AuthorizationFilter` asks the query performer, and returns **success** when no
+performer is found for the name.
+
+⚠️ `AuthorizationResult` — `record (bool IsAuthorized, string? FailureReason)`
+with `Success` and `Failure(reason)` — is **not** what either filter returns and
+not what `IAuthorizationEvaluator` produces (that returns a plain `bool`). It is
+a standalone type, usable as a command `Provide()` short-circuit value. Do not
+describe it as the filter contract.
+
+## Executing as a system actor
+
+Command authorization reads the principal from the current HTTP request. A
+reactor, hosted service, or one command orchestrating another has no request, so
+any command carrying `[Authorize]` or `[Roles]` is **denied**.
+
+`ISystemExecution` is the way out:
+
+```csharp
+using var scope = systemExecution.AsSystem(nameof(<RoleEnum>.<Member>));
+await pipeline.Execute(new <CommandName>(<args>));
+```
+
+- `AsSystem(params string[] roles)` establishes an authenticated system actor for
+  the scope. With no roles it satisfies `[Authorize]` but no `[Roles]`.
+- `As(ClaimsPrincipal principal)` runs as a specific principal.
+- Disposing restores the previous context.
+
+`SystemPrincipal.AuthenticationType` is `"System"` and `SystemPrincipal.Subject`
+is `"[System]"`, which is what appears in audit trails.
+
+The established principal is consulted **only** when there is no HTTP request
+context, so it can never influence the authorization of an HTTP-origin command.
+`CurrentPrincipalAccessor` implements that: a request principal always wins over
+the ambient override.
+
+Keep the scope as narrow as the work. A broad `AsSystem` around a whole hosted
+service turns every command it touches into a privileged one.

package/skills/cratis-arc-authentication-authorization-and-identity/references/frontend.md

@@ -0,0 +1,102 @@
+# Frontend identity
+
+Verified against `@cratis/arc` and `@cratis/arc.react` `22.10.4`.
+
+## `@cratis/arc/identity`
+
+```ts
+interface IIdentity<TDetails = object> {
+    id: string;
+    name: string;
+    roles: string[];
+    details: TDetails;
+    isSet: boolean;
+    isInRole(role: string): boolean;
+    refresh(): Promise<IIdentity<TDetails>>;
+}
+```
+
+`IdentityProvider` is the framework-neutral implementation:
+
+| Member | Notes |
+| --- | --- |
+| `static readonly CookieName = '.cratis-identity'` | The cookie `/.cratis/me` writes |
+| `static setHttpHeadersCallback(callback)` | Headers to send on the refresh call |
+| `static setApiBasePath(path)` / `static setOrigin(origin)` | Where `/.cratis/me` lives |
+| `static getCurrent<TDetails>(type?)` | Reads the **cookie**, no network call |
+| `static refresh<TDetails>(type?)` | Fetches `<apiBasePath>/.cratis/me` |
+| `static clearIdentityCookie()` | Expires the cookie |
+
+`IIdentityProvider` is an abstract class with a single
+`getCurrent<TDetails>(type?)`, which is what a view model injects.
+
+`IdentityProviderResult` on the wire is
+`{ id: string; name: string; roles: string[]; details: object }`.
+
+`getCurrent` reads the cookie and never touches the network. That is what makes
+it cheap, and also why nothing it returns is a security decision — the cookie is
+deliberately not `HttpOnly`, so the browser can read *and write* it.
+
+## `@cratis/arc.react/identity`
+
+```ts
+interface IIdentityContext<TDetails = object> extends IIdentity<TDetails> {
+    isLoading: boolean;
+    clearIdentity: () => void;
+}
+```
+
+`IdentityProvider` is the React component. Props: `children`,
+`httpHeadersCallback`, and `detailsType` (a constructor, for type-safe details).
+It seeds `isLoading: true` and fetches on mount. The root `<Arc>` component takes
+the same `detailsType` prop and renders this provider for you.
+
+`useIdentity` has two overloads:
+
+```ts
+useIdentity<TDetails>(type: Constructor<TDetails>, defaultDetails?): IIdentityContext<TDetails>
+useIdentity<TDetails>(defaultDetails?): IIdentityContext<TDetails>
+```
+
+The default details stand in **whenever there are no details to give**, not only
+when the identity is explicitly unset — an identity that resolved while carrying
+no details still has `isSet` true, and without the stand-in the first property
+access on the details throws and takes the page down.
+
+`isLoading` distinguishes "the identity has not arrived yet" from "the caller is
+anonymous". Treating the two alike makes a signed-in user flash the forbidden
+state on every load.
+
+## `RequireRole`
+
+```tsx
+<RequireRole roles={[<role>]} whileLoading={<spinner/>} forbidden={<denied/>}>
+    {children}
+</RequireRole>
+```
+
+Props are `RequireRoleSlots` (`children`, `whileLoading?`, `forbidden?`) crossed
+with either `{ roles: string[]; allow? }` or `{ roles?; allow }`, where `allow` is
+`(details: TDetails | undefined, identity: IIdentityContext<TDetails>) => boolean`.
+When both are supplied, **both** must pass.
+
+Everything that is not an unambiguous yes renders `forbidden`:
+
+- neither `roles` nor `allow` supplied (it warns and denies — that is what a
+  renamed configuration key looks like);
+- `roles` supplied but not an array;
+- the identity is not set;
+- no role matches, or the predicate does not return exactly `true`;
+- the predicate throws;
+- an `allow` predicate with absent or `null` details.
+
+⚠️ **This hides UI; it does not protect data.** The identity comes from a cookie
+the browser can edit, so anyone can render these children at will. Every query
+and command behind the gate must carry its own `[Authorize]`/`[Roles]` on the
+server, where the decision cannot be edited.
+
+## MVVM
+
+`@cratis/arc.react.mvvm` has **no** identity hook, provider, context, or type. It
+registers `IIdentityProvider` → `IdentityProvider` in its container so a view
+model can constructor-inject it. That is the whole integration.

package/skills/cratis-arc-authentication-authorization-and-identity/references/local-development.md

@@ -0,0 +1,85 @@
+# Running with an identity locally
+
+Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.10.4`.
+
+## What Arc does not give you
+
+There is **no** development identity provider, **no** fake or seeded principal,
+**no** local sign-in page, and **no** development authentication handler anywhere
+in Arc. `ArcOptions` has no switch that relaxes authentication. The only
+"Development" type in the framework is `DevelopmentTenantIdResolver`, which is a
+deprecated alias over the fixed tenant resolver and has nothing to do with
+identity.
+
+Guidance describing a `.cratis/.ai` local identity route is describing something
+that does not exist.
+
+## What Arc does give you
+
+Two anonymous listing endpoints, both tagged for development in their metadata:
+
+| Route | Returns |
+| --- | --- |
+| `GET /.cratis/users` | Every `User` from every registered `ICanProvideUsers` |
+| `GET /.cratis/tenants` | Every `Tenant` from every registered `ICanProvideTenants` |
+
+```csharp
+public record User(ClientPrincipal MicrosoftIdentity, object Details);
+public interface ICanProvideUsers { Task<IEnumerable<User>> Provide(); }
+```
+
+⚠️ Both are mapped `AllowAnonymous` and **unconditionally** — there is no
+environment check in the mapper. Whatever your implementations return is public
+to anyone who can reach the application. Register them only for a development
+environment, and return fixtures rather than production users or tenants.
+
+## Supplying an identity locally
+
+Because the shipped handler reads forwarded headers, the way to run with an
+identity locally is to send those headers yourself. All three are required:
+
+- `x-ms-client-principal-id`
+- `x-ms-client-principal-name`
+- `x-ms-client-principal` — base64 of the `ClientPrincipal` JSON
+
+```json
+{
+  "identityProvider": "<provider>",
+  "userId": "<id>",
+  "userDetails": "<display name>",
+  "userRoles": ["<role>"],
+  "claims": [{ "typ": "<claim type>", "val": "<value>" }]
+}
+```
+
+Base64-encode that document and send it as `x-ms-client-principal`. `curl`
+example shape:
+
+```bash
+curl -H "x-ms-client-principal-id: <id>" \
+     -H "x-ms-client-principal-name: <name>" \
+     -H "x-ms-client-principal: <base64>" \
+     "https://<host>/.cratis/me"
+```
+
+`NameIdentifier` and `sub` come from the **id header**, not from `userId` in the
+body, so the two must agree if anything downstream reads both.
+
+## A browser cannot set headers on every transport
+
+Server-Sent Events and WebSocket connections opened by the browser cannot carry
+custom request headers. A local setup that authenticates purely by header will
+therefore authenticate ordinary requests and not the observable-query streams.
+
+Arc's own test applications solve this with a **cookie-based** development
+handler carrying the same base64 `ClientPrincipal` under a cookie. That handler
+lives in the test applications, not in any shipped package — if you need it, it
+is an `IAuthenticationHandler` you write in your own application and register
+only for development.
+
+## Do not let development shortcuts become the deployment
+
+Any local mechanism that lets the caller author its own principal is exactly the
+production risk described in [authentication](authentication.md). Keep it behind
+an environment check, and make sure the deployed application is unreachable
+except through the ingress that owns those headers.