@poppykit/client 0.0.0-stage → 0.1.0

package/dist/auth/client-auth.d.ts

@@ -0,0 +1,297 @@
+import type { AuthSelection, AuthStore } from './store.js';
+import type { OperationOwner } from './ownership.js';
+import type { JsonObject } from '../protocol/wire.js';
+import type { CompanyMetadata, MetadataResolver } from '../network/discovery.js';
+import type { HttpTransport } from '../network/transport.js';
+import type { ApiTarget, AgentBrowserController, FeedbackReport } from '../integrations.js';
+export type { AuthStore, AuthSelection };
+export interface SecretStore {
+    stage(secret: string): Promise<string>;
+    read(reference: string): Promise<string | null>;
+    remove(reference: string): Promise<void>;
+}
+export interface IdentitySigner {
+    readonly kid: string;
+    publicJwk(): Promise<JsonObject>;
+    sign(input: Uint8Array): Promise<Uint8Array>;
+}
+export type AssertionRequest = {
+    operationId: string;
+    issuer: string;
+} & ({
+    purpose: 'client-authentication';
+} | {
+    purpose: 'session';
+} | {
+    purpose: 'browser';
+    sessionId: string;
+    returnTo: string;
+});
+export interface AssertionProvider {
+    assert(request: AssertionRequest): Promise<{
+        assertion: string;
+        expiresAt: number;
+    }>;
+}
+export interface ProviderIdentity {
+    identity(issuer: string): Promise<{
+        clientId: string;
+        userId: string;
+    }>;
+}
+export type SignInMethod = 'direct' | 'device' | 'mediated';
+export interface AuthorizationRequirement {
+    requiredScopes: string[];
+    grantedScopes: string[];
+    missingScopes: string[];
+    sufficient: boolean;
+    methods: {
+        method: SignInMethod;
+        scopes: string[];
+    }[];
+    organization: {
+        name: string;
+        domain: string;
+    };
+}
+export interface TrustedInput {
+    collect(request: {
+        operationId: string;
+        issuer: string;
+        organization: {
+            name: string;
+            domain: string;
+        };
+        fields: {
+            name: string;
+            label: string;
+            secret: boolean;
+        }[];
+        challenge?: {
+            id: string;
+            sentTo: string;
+            expiresAt: number;
+        };
+    }): Promise<Record<string, string> | null>;
+}
+export interface SignInInput {
+    method?: SignInMethod;
+    scopes: string[];
+    redirectUri?: string;
+    browserBinding?: string;
+    force?: boolean;
+    requiredExistingScopes?: string[];
+}
+export interface SignInStart {
+    outcome: AuthOutcome;
+    authorizationUrl?: string;
+    device?: {
+        verificationUri: string;
+        verificationUriComplete?: string;
+        userCode: string;
+        organization: {
+            name: string;
+            domain: string;
+        };
+        nextPollAt: number;
+    };
+}
+export interface ClientAuthOptions {
+    namespace: string;
+    localUserId: string;
+    clientId: string;
+    redirectUris: readonly string[];
+    identity?: IdentitySigner;
+    assertions?: AssertionProvider;
+    providerIdentity?: ProviderIdentity;
+    trustedInput?: TrustedInput;
+    store: AuthStore;
+    secrets: SecretStore;
+    transport: HttpTransport;
+    metadata: MetadataResolver;
+    now?: () => number;
+    ownerAlive?: (owner: OperationOwner) => boolean;
+}
+export type ConnectionStatus = 'signed_out' | 'signed_in' | 'disconnected' | 'uncertain';
+export interface Connection {
+    id: string;
+    domain: string;
+    issuer: string;
+    organization: {
+        name: string;
+        domain: string;
+    };
+    sessionId: string | null;
+    generation: number;
+    status: ConnectionStatus;
+    scopes: string[];
+}
+export type OperationStatus = 'pending' | 'completed' | 'denied' | 'expired' | 'cancelled' | 'failed' | 'uncertain';
+export interface AuthOutcome {
+    operationId: string;
+    status: OperationStatus;
+    connection: Connection;
+    error?: string;
+    grantedScopes?: string[];
+    missingScopes?: string[];
+    retryAfterMs?: number;
+    nextAction?: 'wait' | 'sign_in' | 'retry_cleanup';
+}
+export interface SignOutOutcome {
+    connection: Connection;
+    cleanup: 'complete' | 'pending' | 'uncertain';
+}
+export interface ConversationTarget {
+    issuer: string;
+    endpoint: string;
+    resource?: string;
+}
+export interface ClientAuth {
+    start(domain: string, input?: {
+        anonymous?: boolean;
+    }): Promise<AuthOutcome>;
+    get(connectionId: string): Promise<Connection | null>;
+    list(): Promise<Connection[]>;
+    target(connectionId: string): Promise<ConversationTarget>;
+    authorization(connectionId: string, requiredScopes: readonly string[]): Promise<AuthorizationRequirement>;
+    beginSignIn(connectionId: string, input: SignInInput): Promise<SignInStart>;
+    continueSignIn(operationId: string): Promise<AuthOutcome>;
+    completeSignIn(input: {
+        callbackUrl: string;
+        browserBinding: string;
+    }): Promise<AuthOutcome>;
+    cancelSignIn(operationId: string): Promise<AuthOutcome>;
+    operation(operationId: string): Promise<AuthOutcome | null>;
+    renew(connectionId: string, input?: {
+        resource?: string;
+        scopes?: string[];
+    }): Promise<AuthOutcome>;
+    signOut(connectionId: string): Promise<SignOutOutcome>;
+    retryCleanup(connectionId: string): Promise<SignOutOutcome>;
+    recover(): Promise<AuthOutcome[]>;
+    authorizedFetch(connectionId: string, request: Request, target: ConversationTarget, requiredScopes?: readonly string[]): Promise<Response>;
+    apiTarget(connectionId: string, apiUrl: string, destination?: string): Promise<ApiTarget>;
+    apiFetch(connectionId: string, request: Request, target: ApiTarget, requiredScopes?: readonly string[]): Promise<Response>;
+    joinBrowser(connectionId: string, returnTo: string, controller: AgentBrowserController): Promise<void>;
+    feedback(connectionId: string, report: FeedbackReport): Promise<void>;
+}
+export interface CredentialRecord {
+    secretRef: string;
+    tokenType: 'DPoP' | 'Bearer';
+    dpopKeyRef: string;
+    scopes: string[];
+    expiresAt: number;
+    generation: number;
+}
+export interface ConnectionRecord {
+    id: string;
+    domain: string;
+    issuer: string;
+    metadata: CompanyMetadata;
+    userId: string;
+    dpopKeyRef: string;
+    sessionId: string | null;
+    generation: number;
+    status: ConnectionStatus;
+    grantId: string | null;
+    slots: Record<string, CredentialRecord>;
+    anonymous?: boolean;
+    notBefore?: string;
+}
+export interface GrantRecord {
+    id: string;
+    issuer: string;
+    userId: string;
+    secretRef: string;
+    scopes: string[];
+    expiresAt: number | null;
+    generation: number;
+    status: 'active' | 'uncertain' | 'revoking' | 'revoked';
+    operationId: string | null;
+}
+export interface DirectRecord {
+    stateHash: string;
+    verifierRef: string;
+    browserHash: string;
+    redirectUri: string;
+    issuer: string;
+    clientId: string;
+    sessionId: string;
+}
+export interface OperationRecord {
+    owner?: OperationOwner;
+    epoch: string;
+    id: string;
+    kind: 'start' | 'renew' | 'sign_in';
+    connectionId: string;
+    connectionGeneration: number;
+    grantId: string | null;
+    grantGeneration: number | null;
+    phase: 'prepared' | 'dispatched' | 'staged' | 'terminal';
+    status: OperationStatus;
+    createdAt: number;
+    expiresAt: number;
+    resource: string | null;
+    scopes: string[];
+    direct: DirectRecord | null;
+    staged: StagedRefresh | null;
+    result: AuthOutcome | null;
+    method?: SignInMethod;
+    requiredExistingScopes?: string[];
+    signInSessionId?: string;
+    device?: {
+        codeRef: string;
+        intervalMs: number;
+        nextPollAt: number;
+    };
+    mediated?: {
+        challengeId: string;
+        sentTo: string;
+    };
+    cancelRequested?: boolean;
+}
+export interface StagedRefresh {
+    tokenType?: 'DPoP' | 'Bearer';
+    accessRef: string;
+    refreshRef: string | null;
+    sessionId: string;
+    scopes: string[];
+    signedIn: boolean;
+    expiresAt: number;
+    refreshExpiresAt: number | null;
+}
+export interface CleanupRecord {
+    id: string;
+    connectionId: string;
+    issuer: string;
+    revocationEndpoint: string;
+    secretRef: string;
+    status: 'pending' | 'uncertain';
+    notBefore?: string;
+}
+export interface ClientAuthState {
+    version: 1;
+    epoch: string;
+    owner: {
+        namespace: string;
+        clientId: string;
+        localUserId: string;
+    } | null;
+    identities: Record<string, {
+        userId: string;
+        dpopKeyRef: string;
+    }>;
+    connections: Record<string, ConnectionRecord>;
+    grants: Record<string, GrantRecord>;
+    operations: Record<string, OperationRecord>;
+    cleanup: Record<string, CleanupRecord>;
+}
+export declare class AuthFailure extends Error {
+    readonly code: string;
+    readonly connectionId?: string | undefined;
+    readonly retryAfterMs?: number | undefined;
+    readonly retryAt?: string | undefined;
+    constructor(code: string, connectionId?: string | undefined, retryAfterMs?: number | undefined, retryAt?: string | undefined);
+}
+export declare function initialClientAuthState(): ClientAuthState;
+export declare function createClientAuth(options: ClientAuthOptions): ClientAuth;