@securitydept/basic-auth-context-client 0.3.0-beta.1 → 0.3.0-beta.10

package/README.md

@@ -2,4 +2,10 @@
 
 Basic Auth Context Client of the SecurityDept TypeScript SDK, a layered authentication and authorization toolkit built as reusable Rust crates, a TypeScript client SDK workspace, and reference server/web apps.
 
+## Documentation
+
+- [Package documentation](https://www.npmjs.com/package/@securitydept/basic-auth-context-client)
+- [SecurityDept TypeScript SDK guide](https://github.com/ethaxon/securitydept/blob/main/docs/en/007-CLIENT_SDK_GUIDE.md)
+- [SecurityDept architecture](https://github.com/ethaxon/securitydept/blob/main/docs/en/001-ARCHITECTURE.md)
+
 Repository: [ethaxon/securitydept](https://github.com/ethaxon/securitydept)

package/dist/index.d.mts

@@ -1,16 +1,285 @@
-import { a as AuthGuardResultKind, c as BasicAuthContextClientConfig, i as AuthGuardResult, l as BasicAuthZoneConfig, n as readBasicAuthBoundaryKind, o as BasicAuthBoundaryKind, r as AuthGuardRedirectStatus, s as BasicAuthBoundaryObservation, t as BasicAuthContextClient, u as ResolvedBasicAuthZone } from "./client-DU98lpa_.mjs";
-
-//#region src/schemas.d.ts
+import { CancellationTokenOptions, ClientError, DisposableTrait, EventStreamTrait, FoundationEnvironment, ReadableSignalTrait, ResourceSnapshot, ResourceTrait, SYMBOL_DISPOSE, SecuritydeptInjectorTrait, SecuritydeptProvider, SpanTrait } from "@securitydept/client";
+//#region src/authorization-header.d.ts
+interface CreateBasicAuthorizationHeaderValueOptions {
+  readonly username: string;
+  readonly password: string;
+}
+declare function createBasicAuthorizationHeaderValue(options: CreateBasicAuthorizationHeaderValueOptions): string;
+//#endregion
+//#region src/types.d.ts
+interface BasicAuthZoneConfig {
+  /** URL path prefix for this zone (e.g. "/basic"). */
+  zonePrefix: string;
+  /** Login subpath relative to zone prefix (default: "/login"). */
+  loginSubpath?: string;
+}
+/** Configuration for the Basic Auth Context Client. */
+interface BasicAuthContextClientConfig {
+  id?: string;
+  /** Base URL of the SecurityDept server. */
+  baseUrl: string;
+  /** One or more Basic Auth zones to manage. */
+  zones: BasicAuthZoneConfig[];
+  /** Protected endpoint used by start()/refresh() to observe the boundary. */
+  probePath?: string;
+  autoStart?: boolean;
+  tracing?: BasicAuthContextClientTracingOptions;
+}
+interface BasicAuthContextClientTracingOptions {
+  target?: string;
+  prefix?: string;
+}
+interface ResolvedBasicAuthContextClientConfig {
+  id: string;
+  baseUrl: string;
+  zones: readonly ResolvedBasicAuthZone[];
+  probePath?: string;
+  tracing: Required<BasicAuthContextClientTracingOptions>;
+}
+declare const BasicAuthBoundaryKind: {
+  readonly Authenticated: "authenticated";
+  readonly Challenge: "challenge";
+  readonly Unauthorized: "unauthorized";
+};
+type BasicAuthBoundaryKind = (typeof BasicAuthBoundaryKind)[keyof typeof BasicAuthBoundaryKind];
+interface BasicAuthBoundaryObservation {
+  status: number;
+  challengeHeader?: string | null;
+  requestPath?: string;
+}
+interface BasicAuthBoundarySnapshot {
+  authenticated: boolean;
+  boundaryKind: BasicAuthBoundaryKind;
+  status: number;
+  path: string;
+  challengeHeader: string | null;
+  zone?: ResolvedBasicAuthZone;
+}
+declare const BasicAuthContextEventType: {
+  readonly BoundaryRefreshStarted: "basic_auth.boundary.refresh.started";
+  readonly BoundaryRefreshSucceeded: "basic_auth.boundary.refresh.succeeded";
+  readonly BoundaryRefreshFailed: "basic_auth.boundary.refresh.failed";
+  /** These logout events describe local boundary-projection clearing only. */
+  readonly LogoutStarted: "basic_auth.logout.started";
+  readonly LogoutSucceeded: "basic_auth.logout.succeeded";
+  readonly LogoutFailed: "basic_auth.logout.failed";
+  readonly LoginRedirectStarted: "basic_auth.login.redirect.started";
+  readonly LoginRedirectSucceeded: "basic_auth.login.redirect.succeeded";
+  readonly LoginRedirectFailed: "basic_auth.login.redirect.failed";
+};
+type BasicAuthContextEventType = (typeof BasicAuthContextEventType)[keyof typeof BasicAuthContextEventType];
+interface BasicAuthContextEventBase {
+  readonly at: number;
+  readonly client: {
+    readonly id: string;
+  };
+}
+type BasicAuthContextEventData = {
+  readonly type: typeof BasicAuthContextEventType.BoundaryRefreshStarted;
+  readonly snapshot: BasicAuthBoundarySnapshot | null;
+} | {
+  readonly type: typeof BasicAuthContextEventType.BoundaryRefreshSucceeded;
+  readonly snapshot: BasicAuthBoundarySnapshot;
+  readonly zone?: ResolvedBasicAuthZone;
+} | {
+  readonly type: typeof BasicAuthContextEventType.BoundaryRefreshFailed;
+  readonly snapshot: BasicAuthBoundarySnapshot | null;
+  readonly error: ClientError;
+} | {
+  readonly type: typeof BasicAuthContextEventType.LogoutStarted;
+  readonly snapshot: BasicAuthBoundarySnapshot | null;
+} | {
+  readonly type: typeof BasicAuthContextEventType.LogoutSucceeded;
+  readonly snapshot: null;
+} | {
+  readonly type: typeof BasicAuthContextEventType.LogoutFailed;
+  readonly snapshot: BasicAuthBoundarySnapshot | null;
+  readonly error: ClientError;
+} | {
+  readonly type: typeof BasicAuthContextEventType.LoginRedirectStarted | typeof BasicAuthContextEventType.LoginRedirectSucceeded;
+  readonly zone: ResolvedBasicAuthZone;
+} | {
+  readonly type: typeof BasicAuthContextEventType.LoginRedirectFailed;
+  readonly zone: ResolvedBasicAuthZone;
+  readonly error: ClientError;
+};
+type BasicAuthContextEvent = BasicAuthContextEventBase & BasicAuthContextEventData;
+interface BasicAuthContextOperationSignals {
+  readonly startPending: ReadableSignalTrait<boolean>;
+  readonly refreshPending: ReadableSignalTrait<boolean>;
+  readonly logoutPending: ReadableSignalTrait<boolean>;
+  readonly loginRedirectPending: ReadableSignalTrait<boolean>;
+}
+interface BasicAuthRefreshOptions extends CancellationTokenOptions {
+  path?: string;
+}
+type BasicAuthZoneSelectionOptions = {
+  currentPath: string;
+  zonePrefix?: never;
+} | {
+  zonePrefix: string;
+  currentPath?: never;
+};
+/** Options for clearing the client's in-memory boundary projection. */
+interface BasicAuthLogoutOptions extends CancellationTokenOptions {}
+type BasicAuthLoginWithRedirectOptions = BasicAuthZoneSelectionOptions & CancellationTokenOptions & {
+  postAuthRedirectUri?: string;
+};
+declare const AuthGuardResultKind: {
+  readonly Ok: "ok";
+  readonly Redirect: "redirect";
+};
+type AuthGuardResultKind = (typeof AuthGuardResultKind)[keyof typeof AuthGuardResultKind];
+declare const AuthGuardRedirectStatus: {
+  readonly Found: 302;
+  readonly SeeOther: 303;
+  readonly TemporaryRedirect: 307;
+};
+type AuthGuardRedirectStatus = (typeof AuthGuardRedirectStatus)[keyof typeof AuthGuardRedirectStatus];
+/** Redirect instruction — framework-neutral result. */
+type AuthGuardResult<T> = {
+  kind: typeof AuthGuardResultKind.Ok;
+  value: T;
+} | {
+  kind: typeof AuthGuardResultKind.Redirect;
+  status: AuthGuardRedirectStatus;
+  location: string;
+};
+/** Resolved zone with computed paths. */
+interface ResolvedBasicAuthZone {
+  zonePrefix: string;
+  loginPath: string;
+}
+interface BasicAuthContextClientStateSignals {
+  readonly boundarySnapshot: ReadableSignalTrait<ResourceSnapshot<BasicAuthBoundarySnapshot | null>>;
+  readonly boundaryResource: ResourceTrait<BasicAuthBoundarySnapshot | null>;
+  readonly isAuthenticated: ResourceTrait<boolean>;
+}
+//#endregion
+//#region src/client.d.ts
+declare function readBasicAuthBoundaryKind(options: BasicAuthBoundaryObservation): BasicAuthBoundaryKind;
 /**
- * Schema for validating BasicAuthContextClientConfig.
+ * Basic Auth Context Client.
  *
- * Validates:
- *   - `baseUrl` is a non-empty string
- *   - `zones` is a non-empty array of valid zone configs
- *   - each zone has a non-empty `zonePrefix`
- *   - optional fields have correct types when provided
+ * Owns zone-aware Basic Auth boundary observations and login navigation.
+ * It does not manage browser credentials or principal data.
  */
-declare const BasicAuthContextClientConfigSchema: any;
+declare class BasicAuthContextClient implements DisposableTrait {
+  [SYMBOL_DISPOSE]: () => void;
+  static defaultOptions: {
+    readonly loginSubpath: "/login";
+    readonly tracing: {
+      readonly target: "basic-auth-context-client";
+      readonly prefix: "basic_auth_context";
+    };
+  };
+  private readonly _environment;
+  private readonly _config;
+  private readonly _span;
+  private readonly _rootCancellation;
+  private readonly _destroyed;
+  private readonly destroyed$;
+  private readonly _boundarySnapshotSignal;
+  private readonly _operationSignals;
+  private readonly _eventSubject;
+  private readonly _refreshCommandSubject;
+  private readonly _refreshResponseSubject;
+  private readonly _startOnce;
+  readonly id: string;
+  readonly zones: readonly ResolvedBasicAuthZone[];
+  readonly boundarySnapshot: ReadableSignalTrait<ResourceSnapshot<BasicAuthBoundarySnapshot | null>>;
+  readonly boundaryResource: ResourceTrait<BasicAuthBoundarySnapshot | null>;
+  readonly isAuthenticated: ResourceTrait<boolean>;
+  readonly operations: BasicAuthContextOperationSignals;
+  readonly events: EventStreamTrait<BasicAuthContextEvent>;
+  protected get environment(): FoundationEnvironment;
+  protected get span(): SpanTrait;
+  protected get config(): ResolvedBasicAuthContextClientConfig;
+  static fromEnvironmentConfig(options: {
+    readonly config: BasicAuthContextClientConfig;
+    readonly environment: FoundationEnvironment;
+  }): BasicAuthContextClient;
+  static fromInjector(injector: SecuritydeptInjectorTrait): BasicAuthContextClient;
+  protected constructor(config: BasicAuthContextClientConfig, environment: FoundationEnvironment);
+  start(): Promise<BasicAuthBoundarySnapshot>;
+  private _start;
+  refresh(options?: BasicAuthRefreshOptions): Promise<BasicAuthBoundarySnapshot>;
+  private _refresh;
+  /**
+   * Clears only this client's in-memory Basic Auth boundary projection.
+   *
+   * Browsers own HTTP Basic credentials. This method cannot revoke or clear
+   * those credentials, and a later probe may observe an authenticated state
+   * again when the browser continues sending them.
+   */
+  logout(options?: BasicAuthLogoutOptions): Promise<void>;
+  private _logout;
+  loginWithRedirect(options: BasicAuthLoginWithRedirectOptions): Promise<void>;
+  private _loginWithRedirect;
+  /** Find the zone that contains the given path. */
+  zoneForPath(path: string): ResolvedBasicAuthZone | undefined;
+  zoneForPrefix(zonePrefix: string): ResolvedBasicAuthZone | undefined;
+  /** Check whether a path falls inside any configured zone. */
+  isInZone(path: string): boolean;
+  /** Build the full login URL for a zone, optionally with a post-auth redirect. */
+  loginUrl(zone: ResolvedBasicAuthZone, postAuthRedirectUri?: string): string;
+  loginUrlForZonePrefix(zonePrefix: string, postAuthRedirectUri?: string): string | null;
+  /**
+   * Handle a 401 response: if the current path is inside a zone,
+   * return a redirect instruction to the zone's login URL.
+   */
+  handleUnauthorized(currentPath: string, responseStatus: number): AuthGuardResult<null>;
+  dispose(): void;
+  private _resolveRefreshOptions;
+  private _resolveZoneForAction;
+  private _dispatchRefresh;
+  private _executeRefresh;
+  private _snapshotFromResponse;
+  private _readCurrentSnapshot;
+  private _emitEvent;
+}
+//#endregion
+//#region src/error.d.ts
+declare const BasicAuthContextErrorCode: {
+  readonly OperationFailed: "basic_auth.operation_failed";
+  readonly InvalidConfig: "basic_auth.invalid_config";
+  readonly ClientDisposed: "basic_auth.client_disposed";
+  readonly RouterUnavailable: "basic_auth.router_unavailable";
+  readonly ProbePathRequired: "basic_auth.probe_path_required";
+  readonly ZoneNotFound: "basic_auth.zone_not_found";
+  readonly ZoneRequired: "basic_auth.zone_required";
+};
+type BasicAuthContextErrorCode = (typeof BasicAuthContextErrorCode)[keyof typeof BasicAuthContextErrorCode];
+declare const BasicAuthContextSource: {
+  readonly BasicAuthContext: "basic-auth-context";
+};
+type BasicAuthContextSource = (typeof BasicAuthContextSource)[keyof typeof BasicAuthContextSource];
+//#endregion
+//#region src/providers.d.ts
+interface ProvideBasicAuthContextOptions {
+  readonly config: BasicAuthContextClientConfig;
+}
+declare function provideBasicAuthContext(options: ProvideBasicAuthContextOptions): readonly SecuritydeptProvider[];
+//#endregion
+//#region src/schemas.d.ts
+declare const BasicAuthContextClientConfigSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+  baseUrl: string;
+  zones: {
+    zonePrefix: string;
+    loginSubpath?: string | undefined;
+  }[];
+  id?: string | undefined;
+  probePath?: string | undefined;
+  autoStart?: boolean | undefined;
+  tracing?: {
+    target?: string | undefined;
+    prefix?: string | undefined;
+  } | undefined;
+}, {}>;
+//#endregion
+//#region src/tokens.d.ts
+declare const BASIC_AUTH_CONTEXT_CLIENT: any;
+declare const BASIC_AUTH_CONTEXT_CLIENT_CONFIG: any;
 //#endregion
-export { AuthGuardRedirectStatus, type AuthGuardResult, AuthGuardResultKind, BasicAuthBoundaryKind, type BasicAuthBoundaryObservation, BasicAuthContextClient, type BasicAuthContextClientConfig, BasicAuthContextClientConfigSchema, type BasicAuthZoneConfig, type ResolvedBasicAuthZone, readBasicAuthBoundaryKind };
+export { AuthGuardRedirectStatus, type AuthGuardResult, AuthGuardResultKind, BASIC_AUTH_CONTEXT_CLIENT, BASIC_AUTH_CONTEXT_CLIENT_CONFIG, BasicAuthBoundaryKind, type BasicAuthBoundaryObservation, type BasicAuthBoundarySnapshot, BasicAuthContextClient, type BasicAuthContextClientConfig, BasicAuthContextClientConfigSchema, type BasicAuthContextClientStateSignals, type BasicAuthContextClientTracingOptions, BasicAuthContextErrorCode, type BasicAuthContextEvent, BasicAuthContextEventType, type BasicAuthContextOperationSignals, BasicAuthContextSource, type BasicAuthLoginWithRedirectOptions, type BasicAuthLogoutOptions, type BasicAuthRefreshOptions, type BasicAuthZoneConfig, type CreateBasicAuthorizationHeaderValueOptions, type ProvideBasicAuthContextOptions, type ResolvedBasicAuthContextClientConfig, type ResolvedBasicAuthZone, createBasicAuthorizationHeaderValue, provideBasicAuthContext, readBasicAuthBoundaryKind };
 //# sourceMappingURL=index.d.mts.map