/**
 * Provider-neutral learner identity contract.
 *
 * This module deliberately does not authenticate requests yet. The current
 * resolver reports that no learner identity provider is configured and never
 * manufactures a principal from request headers, IP addresses, ACCESS_CODE,
 * or the browser's anonymous learner key.
 */

export type PrincipalKind = 'user' | 'device' | 'ops' | 'service';

export type PrincipalAuthMethod = 'session' | 'device-proof' | 'ops-cookie' | 'service-bearer';

export interface RequestPrincipal {
  /** Stable platform-owned identifier, independent of any login provider. */
  readonly principalId: string;
  readonly kind: PrincipalKind;
  readonly userId?: string;
  readonly deviceId?: string;
  readonly tenantId?: string;
  readonly sessionId?: string;
  readonly capabilities: readonly string[];
  readonly authMethod: PrincipalAuthMethod;
}

export type PrincipalResolution =
  | { readonly state: 'authenticated'; readonly principal: RequestPrincipal }
  | { readonly state: 'anonymous' }
  | {
      readonly state: 'unavailable';
      readonly reason: 'resolver_not_configured' | 'resolver_failed';
    };

export type RequestPrincipalResolver = (
  request: Request,
) => PrincipalResolution | Promise<PrincipalResolution>;

/**
 * Current learner resolver: explicitly unavailable until a real session or
 * device-proof verifier is selected and implemented.
 */
export const resolveRequestPrincipal: RequestPrincipalResolver = async (_request) => ({
  state: 'unavailable',
  reason: 'resolver_not_configured',
});