Auth

Remarks

This value does not write logs, traces, metrics, or persistent audit records. Host applications own audit transport, retention, redaction, and access control. Metadata should remain non-sensitive and diagnostic.

Remarks

AppSurfaceUser is not a claims principal, identity-provider user, or authorization policy result. Host adapters should map their security system into this passive value only after authenticating the subject. Metadata is copied with ordinal keys and should be treated as context, not as authority for authorization decisions.

Remarks

Session timestamps use DateTimeOffset so host adapters can preserve their original offset. AppSurface does not convert, refresh, revoke, store, or validate the backing host session.

Remarks

The prompt is passive. It never writes cookies, challenges a caller, redirects a response, or invokes an identity provider. Host UI or host adapters decide whether and how to act on it.

Remarks

The prompt is passive. It never clears cookies, signs out a caller, redirects a response, or invokes an identity provider. Host UI or host adapters decide whether and how to act on it.

Remarks

A context with no User is a valid anonymous context. The context does not evaluate policies, read the current request, or wrap ASP.NET Core ClaimsPrincipal ; host-specific adapters own those mappings.

Remarks

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. The appsurface. prefix is reserved for AppSurface-owned keys so future typed properties can migrate existing metadata without key collisions.

Remarks

Hosts may add a stable subcode to the canonical family for the typed outcome, such as agent-approval.consumption-denied.grant-missing . Do not use display messages as machine-readable branching values, and do not renumber public outcome enums after release.

Remarks

The value belongs to the host's agent namespace. It is not an application-user id, a user permission, a bearer token, or evidence that the agent may act. ToString redacts the raw value by default.

Remarks

A host can derive this reference from ExternalSubject , an app-owned identity, or another validated subject namespace. The reference is not an agent grant or a reusable approval credential. ToString redacts the raw value by default.

Remarks

The binding profile and digest are opaque host values. Hosts must use the same profile, normalisation rules, and safe digest representation when issuing and consuming a receipt. This type does not prescribe canonicalisation, cryptography, persistence, or a workflow runtime. ToString intentionally redacts binding values.

Remarks

This metadata aids host policy and confirmation presentation. It does not classify untrusted agent input, grant authority, or replace a host's policy evaluation.

Remarks

The request is immutable and contains only host-safe display fields. It does not carry user credentials, bearer tokens, an agent grant, an approval receipt, or permission to execute the action.

Remarks

This type is passive. Hosts choose how to render a confirmation card, re-evaluate current authority, and issue an opaque receipt after approval. A changed action must be submitted as a new AgentActionRequest ; hosts must not edit an approved request in place.

Remarks

The decision does not evaluate policy, issue a receipt, or execute an action. The diagnostic code must be the canonical family for Kind or a stable subcode in that family; consumers branch on Kind rather than on a display message or subcode.

Remarks

The receipt is not a bearer-token format, signature, database record, or transport message. Hosts own issuance, storage, revocation, atomic one-use consumption, current-authority checks, and execution. Use FromConfirmedRequest to issue a new receipt after durable human approval. Direct construction supports host-owned data reconstruction; it neither proves issuance nor authorizes execution. ToString redacts the opaque receipt reference by default.

Remarks

This result does not consume a receipt or retry an action. Hosts return it after their atomic claim and current authority, grant, state, expiry, revocation, and binding checks complete.

Remarks

Hosts own audit event delivery and should use only display-safe values. This contract must not be treated as proof that an audit sink persisted an event successfully.

Remarks

This result family is intentionally separate from AppSurfaceAuthResult . Authentication, policy, and navigation outcomes remain host-auth decisions; identity resolution describes the app-owned mapping step that can happen after the host has authenticated a subject. Messages and metadata should be display-safe and avoid raw subjects, emails, tokens, and provider payloads by default.

Remarks

Applications implement this interface with their own persistence, provisioning, disabled-user, and duplicate-mapping policies. Implementations should make successful resolution idempotent for the same ExternalSubject tuple, honor cancellation before starting expensive work and while awaiting I/O, and handle concurrent first-time resolution without creating duplicate app users.

Prefer enforcing uniqueness at the mapping store with a unique constraint over the external subject tuple (issuer, subject, and partition key), then make competing inserts converge on the same app user id through optimistic concurrency or a transaction retry. Stores that cannot enforce uniqueness should use an equivalent first-provisioning guard, such as a short distributed lock scoped to the external subject tuple.

Avoid a check-then-insert flow that reads a missing mapping and blindly creates a new app user. Concurrent sign-ins can otherwise provision duplicate app users before either caller observes the other mapping.

Remarks

AppSurfaceAuthResult describes an auth decision; it does not challenge, forbid, redirect, evaluate policies, sign users in, or sign users out. Host-specific packages map these outcomes to platform behavior.

Remarks

This boundary-preview type is intentionally empty. It exists so future AppSurface auth contracts can add settings through a stable options root after those contracts are proven. It does not configure authentication schemes, authorization policies, user or session access, tenant behavior, identity providers, cookies, bearer tokens, challenges, forbids, middleware, endpoint filters, or UI. Host applications must keep those choices in their host-specific security configuration until a later AppSurface package explicitly owns them.

Remarks

The context is an input to an app-owned resolver. It may carry safe correlation, issuer, tenant, or provisioning policy hints, but those hints are not authority unless the application validates them against its own security and persistence rules. Metadata is copied with ordinal keys.

Remarks

The uniqueness key is the ordinal tuple of Issuer , Subject , and optional PartitionKey . Use PartitionKey only for host-validated realm, tenant, client, or environment context that is part of the subject namespace. AppSurface does not treat the partition as tenant authority or authorization truth. The raw values are intentionally omitted from ToString .

Remarks

AppSurfaceAuthModule is a boundary-preview module. It gives AppSurface packages a stable place to compose future auth contracts without taking a dependency on ASP.NET Core authentication, authorization policies, identity providers, middleware, endpoint filters, cookies, bearer tokens, or UI. Registering this module does not sign users in, inspect requests, challenge callers, forbid callers, or enforce authorization; host applications must continue to configure those behaviors in their host-specific security stack.

Remarks

AppUserId belongs to the consuming application. AppSurface does not allocate ids, prescribe storage, or treat the id as a permission source. The value is intentionally omitted from ToString so accidental logs and diagnostics do not disclose user identifiers by default.