@aep-foundation/agent 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,276 @@
+import { EnrollResponse, AepGrantType, AepBuiltInGrantResponse, AepSigningAlgorithm, InspectDocument, AepHttpCommand, RevokeResponse, StatusResponse, AepClientAssertionClaims, AepAuthenticatedCommand, AepProblemDetails, AepImportableJoseKey } from '@aep-foundation/core';
+import { PlatformDiscoveryDocument, PlatformAgentIdentity } from '@aep-foundation/platform';
+
+type Awaitable<T> = T | Promise<T>;
+interface AepClientAssertionSignerContext {
+    command: AepAuthenticatedCommand;
+    serviceDid: string;
+    signingAlgorithms: AepSigningAlgorithm[];
+}
+type AepClientAssertionSigner = (claims: AepClientAssertionClaims, context: AepClientAssertionSignerContext) => Awaitable<string>;
+interface AepAgentOptions {
+    assertionClock?: () => Date;
+    assertionJti?: () => string;
+    assertionTtlSeconds?: number;
+    credentialStore?: AgentCredentialStore;
+    identityProvider: AgentIdentityProvider;
+    identityStore?: AgentIdentityStore;
+    idempotencyKeys?: AgentIdempotencyKeyProvider;
+    inspectCache?: AgentInspectCache;
+}
+interface InspectServiceOptions {
+    serviceUrl: string | URL;
+}
+interface InspectServiceResult {
+    document: InspectDocument;
+    inspectUrl: URL;
+    commandUrl(command: AepHttpCommand): URL;
+    cacheControl?: string;
+    etag?: string;
+}
+interface DiscoverPlatformOptions {
+    platformUrl: string | URL;
+}
+interface DiscoverPlatformResult {
+    document: PlatformDiscoveryDocument;
+    discoveryUrl: URL;
+    endpointUrl(endpoint: keyof PlatformDiscoveryDocument["endpoints"]): URL;
+}
+interface ProvisionPlatformIdentityOptions {
+    authorization?: string;
+    discovery?: DiscoverPlatformResult;
+    idempotencyKey: string;
+    platformUrl: string | URL;
+    serviceDid: string;
+}
+type ProvisionPlatformIdentityResult = AepCommandResult<PlatformAgentIdentity>;
+interface PlatformDelegatedSignerOptions {
+    authorization?: string;
+    discovery?: DiscoverPlatformResult;
+    identity: PlatformAgentIdentity;
+    platformUrl: string | URL;
+}
+interface AepCommandResult<TBody> {
+    body: TBody;
+    commandUrl: URL;
+    status: number;
+}
+interface AepCommandOptions {
+    agentDid?: string;
+    assertionClock?: () => Date;
+    assertionJti?: () => string;
+    assertionTtlSeconds?: number;
+    clientAssertion?: string;
+    clientAssertionSigner?: AepClientAssertionSigner;
+    inspect?: InspectServiceResult;
+    serviceUrl: string | URL;
+}
+interface EnrollServiceOptions extends AepCommandOptions {
+    agentDid: string;
+    claims?: Record<string, unknown>;
+    idempotencyKey: string;
+}
+type EnrollServiceResult = AepCommandResult<EnrollResponse>;
+interface GrantServiceOptions extends AepCommandOptions {
+    grantType: AepGrantType;
+    idempotencyKey: string;
+    parameters?: Record<string, unknown>;
+    requestedScopes?: string[];
+}
+type GrantServiceResult = AepCommandResult<AepBuiltInGrantResponse | Record<string, unknown>>;
+type RevokeServiceSelector = {
+    allGrantTypes: true;
+    credentialId?: never;
+    grantType?: never;
+} | {
+    allGrantTypes?: never;
+    credentialId: string;
+    grantType?: never;
+} | {
+    allGrantTypes?: never;
+    credentialId?: never;
+    grantType: AepGrantType;
+};
+type RevokeServiceOptions = AepCommandOptions & RevokeServiceSelector & {
+    idempotencyKey: string;
+    parameters?: Record<string, unknown>;
+};
+type RevokeServiceResult = AepCommandResult<RevokeResponse>;
+type AgentRevokeServiceOptions = RevokeServiceOptions;
+type StatusServiceOptions = AepCommandOptions;
+type StatusServiceResult = AepCommandResult<StatusResponse>;
+interface BuildClientAssertionClaimsOptions {
+    agentDid: string;
+    command: AepAuthenticatedCommand;
+    clock?: () => Date;
+    jti?: string | (() => string);
+    serviceDid: string;
+    ttlSeconds?: number;
+}
+interface SignClientAssertionOptions extends BuildClientAssertionClaimsOptions {
+    signer: AepClientAssertionSigner;
+    signingAlgorithms?: AepSigningAlgorithm[];
+}
+interface JwtClientAssertionSignerOptions {
+    alg?: AepSigningAlgorithm;
+    key: AepImportableJoseKey;
+    kid?: string;
+    typ?: string;
+}
+interface ClientAssertionAuthenticationHeadersOptions extends Omit<SignClientAssertionOptions, "command" | "serviceDid" | "signingAlgorithms"> {
+    command?: AepAuthenticatedCommand;
+    inspect?: InspectDocument | InspectServiceResult;
+    serviceDid?: string;
+    signingAlgorithms?: AepSigningAlgorithm[];
+}
+type ProtectedResourceAuthenticationHeadersOptions = {
+    credential: AepBuiltInGrantResponse;
+} | ClientAssertionAuthenticationHeadersOptions;
+interface SelectGrantTypeOptions {
+    preferredGrantTypes?: AepGrantType[];
+}
+interface AepSessionCredentialRecord {
+    credential: AepBuiltInGrantResponse | Record<string, unknown>;
+    credentialId: string;
+    expiresAt?: string;
+    grantType: AepGrantType;
+    issuedAt: string;
+    serviceDid: string;
+    serviceUrl?: string;
+}
+type AgentCredentialRecord = AepSessionCredentialRecord;
+interface AgentCredentialStore {
+    deleteCredential(serviceDid: string, credentialId: string): Awaitable<void>;
+    findCredential(serviceDid: string, credentialId: string): Awaitable<AgentCredentialRecord | undefined>;
+    findUsableCredential(serviceDid: string, now?: Date): Awaitable<AgentCredentialRecord | undefined>;
+    listCredentials(serviceDid: string): Awaitable<AgentCredentialRecord[]>;
+    saveCredential(record: AgentCredentialRecord): Awaitable<AgentCredentialRecord>;
+}
+type AepSessionCredentialStore = AgentCredentialStore;
+interface AgentServiceIdentity {
+    agentDid: string;
+    identityKind: "platform-hosted" | "sovereign";
+    metadata?: Record<string, unknown>;
+    serviceDid: string;
+    signingAlgorithms: AepSigningAlgorithm[];
+}
+interface AgentIdentityProviderGetOrCreateInput {
+    inspect: InspectDocument;
+    serviceDid: string;
+    serviceUrl: string;
+}
+interface AgentIdentityProvider {
+    getOrCreateIdentity(input: AgentIdentityProviderGetOrCreateInput): Awaitable<AgentServiceIdentity>;
+    signerFor(identity: AgentServiceIdentity): Awaitable<AepClientAssertionSigner>;
+}
+interface AgentIdentityStore {
+    findByServiceDid(serviceDid: string): Awaitable<AgentServiceIdentity | undefined>;
+    saveIdentity(identity: AgentServiceIdentity): Awaitable<AgentServiceIdentity>;
+}
+interface AgentOperationKey {
+    command: AepAuthenticatedCommand;
+    credentialId?: string;
+    grantType?: AepGrantType;
+    serviceDid: string;
+    serviceUrl: string;
+}
+interface AgentIdempotencyKeyProvider {
+    createKey(operation: AgentOperationKey): Awaitable<string>;
+}
+interface CachedInspectServiceResult extends InspectServiceResult {
+    cachedAt: string;
+}
+interface AgentInspectCache {
+    get(serviceUrl: string): Awaitable<CachedInspectServiceResult | undefined>;
+    set(serviceUrl: string, result: CachedInspectServiceResult): Awaitable<void>;
+}
+interface CreatePlatformIdentityProviderOptions {
+    authorization?: string;
+    idempotencyKey?: string | ((input: AgentIdentityProviderGetOrCreateInput) => string);
+    platformUrl: string | URL;
+}
+interface AgentServiceSessionOptions {
+    serviceUrl: string | URL;
+}
+interface AgentEnrollSessionOptions {
+    claims?: Record<string, unknown>;
+    idempotencyKey?: string;
+}
+interface AgentGrantSessionOptions {
+    grantType?: AepGrantType;
+    idempotencyKey?: string;
+    parameters?: Record<string, unknown>;
+    preferredGrantTypes?: AepGrantType[];
+    requestedScopes?: string[];
+}
+type AgentRevokeSessionOptions = RevokeServiceSelector & {
+    idempotencyKey?: string;
+    parameters?: Record<string, unknown>;
+};
+interface AgentAuthenticationHeadersOptions {
+    preferCredential?: boolean;
+}
+interface AepServiceSession {
+    authenticationHeaders(options?: AgentAuthenticationHeadersOptions): Promise<Record<string, string>>;
+    enroll(options?: AgentEnrollSessionOptions): Promise<EnrollServiceResult>;
+    grant(options?: AgentGrantSessionOptions): Promise<GrantServiceResult>;
+    identity(): Promise<AgentServiceIdentity>;
+    inspect(): Promise<InspectServiceResult>;
+    revoke(options: AgentRevokeSessionOptions): Promise<RevokeServiceResult>;
+    status(): Promise<StatusServiceResult>;
+}
+type FetchLike = (input: URL | string, init?: RequestInit) => Promise<ResponseLike>;
+interface ResponseLike {
+    ok: boolean;
+    status: number;
+    statusText?: string;
+    headers: HeadersLike;
+    json(): Promise<unknown>;
+}
+interface HeadersLike {
+    get(name: string): string | null;
+}
+declare class AepInspectError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+declare class AepCommandError extends Error {
+    readonly problem?: AepProblemDetails;
+    readonly status: number;
+    constructor(message: string, status: number, problem?: AepProblemDetails);
+}
+interface AepAgent {
+    serviceSession(options: AgentServiceSessionOptions): AepServiceSession;
+}
+declare function createAepAgent(options: AepAgentOptions): AepAgent;
+declare function buildClientAssertionClaims(options: BuildClientAssertionClaimsOptions): AepClientAssertionClaims;
+declare function signClientAssertion(options: SignClientAssertionOptions): Promise<string>;
+declare function createJwtClientAssertionSigner(options: JwtClientAssertionSignerOptions): AepClientAssertionSigner;
+declare function discoverPlatform(options: DiscoverPlatformOptions): Promise<DiscoverPlatformResult>;
+declare function provisionPlatformIdentity(options: ProvisionPlatformIdentityOptions): Promise<ProvisionPlatformIdentityResult>;
+declare function createPlatformDelegatedSigner(options: PlatformDelegatedSignerOptions): AepClientAssertionSigner;
+declare function createPlatformIdentityProvider(options: CreatePlatformIdentityProviderOptions): AgentIdentityProvider;
+declare function selectGrantType(inspect: InspectDocument | InspectServiceResult, options?: SelectGrantTypeOptions): AepGrantType;
+declare function createInMemorySessionCredentialStore(records?: AepSessionCredentialRecord[]): AepSessionCredentialStore;
+declare function createInMemoryAgentIdentityStore(records?: AgentServiceIdentity[]): AgentIdentityStore;
+declare function createRandomIdempotencyKeyProvider(generator?: () => string): AgentIdempotencyKeyProvider;
+declare function createInMemoryInspectCache(records?: Array<{
+    result: CachedInspectServiceResult;
+    serviceUrl: string;
+}>): AgentInspectCache;
+declare function sessionCredentialRecordFromGrantResult(result: GrantServiceResult, options: {
+    clock?: () => Date;
+    grantType: AepGrantType;
+    inspect: InspectDocument | InspectServiceResult;
+    serviceUrl?: string | URL;
+}): AepSessionCredentialRecord;
+declare function credentialPresentationHeaders(credential: AepBuiltInGrantResponse): Record<string, string>;
+declare function clientAssertionAuthenticationHeaders(options: ClientAssertionAuthenticationHeadersOptions): Promise<Record<string, string>>;
+declare function protectedResourceAuthenticationHeaders(options: ProtectedResourceAuthenticationHeadersOptions): Promise<Record<string, string>>;
+declare function inspectService(options: InspectServiceOptions): Promise<InspectServiceResult>;
+declare function enrollService(options: EnrollServiceOptions): Promise<EnrollServiceResult>;
+declare function grantService(options: GrantServiceOptions): Promise<GrantServiceResult>;
+declare function revokeService(options: RevokeServiceOptions): Promise<RevokeServiceResult>;
+declare function statusService(options: StatusServiceOptions): Promise<StatusServiceResult>;
+
+export { type AepAgent, type AepAgentOptions, type AepClientAssertionSigner, type AepClientAssertionSignerContext, AepCommandError, type AepCommandOptions, type AepCommandResult, AepInspectError, type AepServiceSession, type AepSessionCredentialRecord, type AepSessionCredentialStore, type AgentAuthenticationHeadersOptions, type AgentCredentialRecord, type AgentCredentialStore, type AgentEnrollSessionOptions, type AgentGrantSessionOptions, type AgentIdempotencyKeyProvider, type AgentIdentityProvider, type AgentIdentityProviderGetOrCreateInput, type AgentIdentityStore, type AgentInspectCache, type AgentOperationKey, type AgentRevokeServiceOptions, type AgentRevokeSessionOptions, type AgentServiceIdentity, type AgentServiceSessionOptions, type Awaitable, type BuildClientAssertionClaimsOptions, type CachedInspectServiceResult, type ClientAssertionAuthenticationHeadersOptions, type CreatePlatformIdentityProviderOptions, type DiscoverPlatformOptions, type DiscoverPlatformResult, type EnrollServiceOptions, type EnrollServiceResult, type FetchLike, type GrantServiceOptions, type GrantServiceResult, type HeadersLike, type InspectServiceOptions, type InspectServiceResult, type JwtClientAssertionSignerOptions, type PlatformDelegatedSignerOptions, type ProtectedResourceAuthenticationHeadersOptions, type ProvisionPlatformIdentityOptions, type ProvisionPlatformIdentityResult, type ResponseLike, type RevokeServiceOptions, type RevokeServiceResult, type SelectGrantTypeOptions, type SignClientAssertionOptions, type StatusServiceOptions, type StatusServiceResult, buildClientAssertionClaims, clientAssertionAuthenticationHeaders, createAepAgent, createInMemoryAgentIdentityStore, createInMemoryInspectCache, createInMemorySessionCredentialStore, createJwtClientAssertionSigner, createPlatformDelegatedSigner, createPlatformIdentityProvider, createRandomIdempotencyKeyProvider, credentialPresentationHeaders, discoverPlatform, enrollService, grantService, inspectService, protectedResourceAuthenticationHeaders, provisionPlatformIdentity, revokeService, selectGrantType, sessionCredentialRecordFromGrantResult, signClientAssertion, statusService };