ForgeTrust.AppSurface.Auth 0.2.0-preview.2

ForgeTrust.AppSurface.Auth

ForgeTrust.AppSurface.Auth provides passive auth contracts for AppSurface modules.

It does not authenticate users, evaluate policies, redirect responses, issue cookies, validate tokens, sign users in, sign users out, or write audit logs. Host applications still own their security stack, such as ASP.NET Core authentication and authorization in a web host.

Use this package when you are authoring AppSurface modules or host integrations that need one surface-neutral vocabulary for users, sessions, auth decisions, login/logout prompts, and auth audit event descriptions.

Release Guidance

AppSurface ships as a coordinated package family. Before installing this package from a prerelease feed, check the package chooser and release hub for current release risk, migration guidance, and readiness.

Use the AppSurface Auth adoption ladder when deciding whether to start with Auth core, the ASP.NET Core adapter, DevAuth, OIDC, Auth.Testing, or raw ASP.NET Core authentication.

Quickstart: Model An Auth Decision

Install the package:

dotnet package add ForgeTrust.AppSurface.Auth

Create a user, session, context, and result:

using ForgeTrust.AppSurface.Auth;

var user = new AppSurfaceUser(
    id: "host-subject-123",
    displayName: "Local Admin",
    metadata: new Dictionary<string, string>
    {
        [AppSurfaceAuthMetadataKeys.TenantId] = "tenant-a"
    });

var session = new AppSurfaceSession(
    id: "session-456",
    startedAt: DateTimeOffset.UtcNow,
    expiresAt: DateTimeOffset.UtcNow.AddHours(1));

var context = new AppSurfaceAuthContext(user, session);
var result = AppSurfaceAuthResult.Forbidden(
    context,
    message: "The current user cannot publish docs.");

if (result.Outcome == AppSurfaceAuthOutcome.Forbid)
{
    // A future host adapter can map this to HTTP 403, a RazorWire forbidden state,
    // or an operator diagnostic. This package does not perform that mapping.
}

What The Package Includes

• AppSurfaceAuthModule
• AppSurfaceAuthOptions
• AppSurfaceUser
• AppSurfaceSession
• AppSurfaceAuthContext
• AppSurfaceAuthResult
• AppSurfaceAuthOutcome
• AppSurfaceAuthReason
• ExternalSubject
• AppUserId
• IAppSurfaceUserIdentityResolver
• AppSurfaceUserIdentityResolutionContext
• AppSurfaceUserIdentityResult
• AppSurfaceUserIdentityStatus
• AppSurfaceLoginPrompt
• AppSurfaceLogoutPrompt
• AppSurfaceAuthAuditEvent
• AppSurfaceAuthMetadataKeys
• Microsoft Options registration for AppSurfaceAuthOptions

What The Package Does Not Include

• Authentication schemes or handlers
• Cookies, JWT bearer, OAuth, OIDC, or ASP.NET Identity integration
• Authorization policies or policy evaluation
• Middleware, endpoint filters, challenges, or forbids
• Request-scoped auth context accessors
• User stores, user provisioning implementation, database schema, or persistence migrations
• Login, logout, redirect, or return-url execution
• RazorWire, web, or UI behavior
• Audit sinks, loggers, metrics, traces, or persistence

Result Outcomes And Reasons

AppSurfaceAuthResult separates high-level outcomes from concrete reasons so callers do not treat host setup failures, user denials, unsafe navigation, and stale sessions as the same kind of failure.

Durable App-User Mapping

OIDC, SAML, cookies, test auth handlers, and enterprise gateways usually give the app an authenticated external subject. Most apps still need a durable app-owned user id for domain records, preferences, ownership, audit trails, and billing. This package defines that boundary without becoming the user store.

Use ExternalSubject for the authenticated external identity tuple:

var subject = new ExternalSubject(
    issuer: "https://login.example.com",
    subject: principalSubject,
    partitionKey: tenantRealm);

The uniqueness key is (Issuer, Subject, PartitionKey) with ordinal comparison. PartitionKey is optional host-validated namespace context for issuers where subject ids are only unique within a realm, tenant, client, or environment. It is not tenant authority and should not be used as a permission source unless the host app validates it through its own security model.

Do not use email, display name, subject alone, tenant id alone, or another mutable profile claim as the durable identity key. Those values can be reassigned, renamed, duplicated across issuers, or corrected by an identity provider without meaning "same app user" in your domain.

Use AppUserId for the durable app-owned user id returned by your app resolver:

public sealed class SqlUserIdentityResolver : IAppSurfaceUserIdentityResolver
{
    public async ValueTask<AppSurfaceUserIdentityResult> ResolveAsync(
        ExternalSubject subject,
        AppSurfaceUserIdentityResolutionContext context,
        CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();

        var appUser = await LoadOrProvisionUserAsync(subject, cancellationToken);
        if (appUser is null)
        {
            return AppSurfaceUserIdentityResult.ProvisioningDenied(
                subject,
                metadata: new Dictionary<string, string>
                {
                    ["correlation_id"] = context.CorrelationId ?? string.Empty
                });
        }

        return AppSurfaceUserIdentityResult.Resolved(
            new AppUserId(appUser.Id),
            subject,
            metadata: new Dictionary<string, string>
            {
                ["resolution"] = appUser.WasCreated ? "provisioned" : "loaded"
            });
    }
}

ResolveAsync(...) is neutral on purpose. Your application chooses whether resolution only loads an existing mapping, creates a user on first sign-in, requires an invite, blocks disabled users, or records an operator review event. Successful resolution should be idempotent for the same external subject tuple, honor cancellation before expensive work and during awaited I/O, and handle concurrent first sign-ins without creating duplicate app users.

Identity resolution failures are separate from AppSurfaceAuthResult:

Copy this pattern:

var subject = new ExternalSubject(issuer, subjectId, partitionKey);
var result = await resolver.ResolveAsync(
    subject,
    new AppSurfaceUserIdentityResolutionContext(correlationId),
    cancellationToken);

if (result.Succeeded)
{
    var appUserId = result.AppUserId!.Value;
}

Do not copy these patterns:

// Do not treat AppSurfaceUser.Id from a host adapter as your durable app user id.
var appUserId = authContext.User?.Id;

// Do not log raw external subject values by default.
logger.LogInformation("Mapped {Issuer} {Subject}", subject.Issuer, subject.Subject);

// Do not rely on tenant or partition metadata as permission truth.
var isAdmin = subject.PartitionKey == "admin";

ExternalSubject.ToString() and AppUserId.ToString() redact raw values by default. Metadata and messages should also avoid raw subject ids, tokens, emails, display names, identity-provider payloads, and database connection details unless the app has an explicit safe-diagnostics policy.

Metadata

Every metadata-bearing contract copies metadata into a read-only dictionary with ordinal keys. Null metadata becomes empty. Keys must be non-empty strings, and values must not be null.

Metadata is context for diagnostics, display, and adapter hand-off. It is not an authorization source of truth unless a host-owned adapter validates the value against the host security system.

Reserved keys live in AppSurfaceAuthMetadataKeys:

• TenantId
• PermissionHints
• AuthenticationScheme
• SubjectId
• CorrelationId

The appsurface. prefix is reserved for AppSurface-owned keys. Keep metadata values primitive and non-sensitive so future typed properties can migrate common keys without breaking existing callers.

Prompt Targets

AppSurfaceLoginPrompt and AppSurfaceLogoutPrompt are passive descriptions. They do not redirect, challenge, sign in, sign out, set cookies, or call identity providers.

Prompt target paths may be null or safe app-relative paths only. Safe paths start with /, are not protocol-relative (//example.com), are not slash-backslash rooted (/\example), contain no backslashes, and contain no control characters. The contracts do not URL-decode input; callers that accept encoded values must decode before creating a prompt.

Host Auth Versus AppSurface Auth Contracts

Use host auth directly when you need to authenticate a request, configure schemes, evaluate policies, issue challenges, forbid callers, validate tokens, or handle identity-provider flows.

Use AppSurface auth contracts when an AppSurface module needs to describe a user, session, decision, prompt, or audit event without depending on a specific host framework.

Use ExternalSubject, AppUserId, and IAppSurfaceUserIdentityResolver when a host-authenticated subject must be mapped to durable app-owned user state. Keep persistence, provisioning policy, tenant authority, and permission checks in the consuming app.

For future CLI authentication, see the AppSurface CLI authenticated command design. CLI auth remains outside this package until the command-gate, token-cache, and non-interactive auth contracts prove which pieces are genuinely surface-neutral.

ASP.NET Core Adapter

Use ForgeTrust.AppSurface.Auth.AspNetCore when an ASP.NET Core host already owns authentication and authorization, but AppSurface-aware code needs mapped request context or named host-policy results.

The ASP.NET Core adapter keeps schemes, policies, middleware, challenges, forbids, redirects, cookies, OIDC, and Identity in the host. It only maps the current request into AppSurfaceAuthContext and ASP.NET Core policy outcomes into AppSurfaceAuthResult.

Today, AppSurfaceUser.Id from the ASP.NET Core adapter is the stable host-owned subject claim selected by the adapter. Treat it as an external subject, not as your durable app-owned user id. A future adapter slice can compose ExternalSubject with IAppSurfaceUserIdentityResolver asynchronously without adding ASP.NET Core dependencies to this package.

Composition

Register AppSurfaceAuthModule from another AppSurface module when you need the auth boundary present in the module graph:

public void RegisterDependentModules(ModuleDependencyBuilder builder)
{
    builder.AddModule<AppSurfaceAuthModule>();
}

That registration composes the boundary and registers AppSurfaceAuthOptions. It has no runtime request effect.