@aep-foundation/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,392 @@
+import { CryptoKey, JWK, KeyObject, JWTHeaderParameters, FlattenedJWSInput, JWTVerifyOptions } from 'jose';
+
+declare const AEP_VERSION = "1.0";
+declare const AEP_MEDIA_TYPE = "application/aep+json";
+declare const AEP_PROBLEM_MEDIA_TYPE = "application/problem+json";
+declare const AEP_AUTH_SCHEME = "AEP";
+declare const AEP_WELL_KNOWN_PATH = "/.well-known/aep";
+declare const DEFAULT_HTTP_ENDPOINT_BASE = "/aep/";
+declare const AEP_COMMANDS: readonly ["inspect", "enroll", "grant", "revoke", "status"];
+declare const AEP_AUTHENTICATED_COMMANDS: readonly ["enroll", "grant", "revoke", "status"];
+declare const AEP_BINDINGS: readonly ["http"];
+declare const AEP_SIGNING_ALGORITHMS: readonly ["EdDSA", "ES256"];
+declare const AEP_IDENTITY_METHOD_DID_WEB = "did:web";
+declare const AEP_GRANT_TYPE_OAUTH_BEARER = "oauth-bearer";
+declare const AEP_GRANT_TYPE_API_KEY = "api-key";
+declare const AEP_GRANT_TYPE_BASIC = "basic";
+declare const AEP_BUILT_IN_GRANT_TYPES: readonly ["oauth-bearer", "api-key", "basic"];
+
+type AepCommand = (typeof AEP_COMMANDS)[number];
+type AepBinding = (typeof AEP_BINDINGS)[number];
+type AepExtensibleString<TValue extends string> = TValue | (string & Record<never, never>);
+type AepSigningAlgorithm = AepExtensibleString<(typeof AEP_SIGNING_ALGORITHMS)[number]>;
+type AepBuiltInGrantType = (typeof AEP_BUILT_IN_GRANT_TYPES)[number];
+type AepGrantType = AepExtensibleString<AepBuiltInGrantType>;
+type AepIdentityMethod = string;
+type AepAuthenticatedCommand = Exclude<AepCommand, "inspect">;
+type AepEnrollmentStatus = "active" | "pending" | "rejected";
+type AepAgentStatus = AepEnrollmentStatus | "suspended" | "terminated" | "unavailable";
+interface InspectDocument {
+    aep_version: string;
+    bindings: {
+        supported: AepBinding[];
+        [key: string]: unknown;
+    };
+    claims?: {
+        required?: string[];
+        preferred?: string[];
+        optional?: string[];
+        [key: string]: unknown;
+    };
+    commands: {
+        supported: AepCommand[];
+        grant_types?: AepGrantType[];
+        grant_types_config?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    core: {
+        signing_algorithms?: AepSigningAlgorithm[];
+        [key: string]: unknown;
+    };
+    extensions?: {
+        supported?: string[];
+        [key: string]: unknown;
+    };
+    http: {
+        endpoint_base: string;
+        [key: string]: unknown;
+    };
+    identity: {
+        methods: AepIdentityMethod[];
+        [key: string]: unknown;
+    };
+    service: {
+        did: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface AepProblemDetails {
+    type: string;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    code: AepExtensibleString<AepErrorCode>;
+    [key: string]: unknown;
+}
+type AepErrorCode = "invalid_request" | "not_recognized" | "identity_suspended" | "identity_terminated" | "identity_unavailable" | "verification_pending" | "unsupported_grant_type" | "idempotency_conflict";
+interface EnrollRequest {
+    agent_did: string;
+    claims?: Record<string, unknown>;
+    idempotency_key: string;
+    [key: string]: unknown;
+}
+interface EnrollResponse {
+    status: AepEnrollmentStatus;
+    owner_action_required?: "true" | "false";
+    requirements_pending?: string[];
+    [key: string]: unknown;
+}
+interface StatusResponse {
+    status: AepAgentStatus;
+    owner_action_required?: "true" | "false";
+    requirements_pending?: string[];
+    since?: string;
+    [key: string]: unknown;
+}
+interface GrantRequest {
+    grant_type: AepGrantType;
+    requested_scopes?: string[];
+    [key: string]: unknown;
+}
+type RevokeRequest = {
+    grant_type: AepGrantType;
+    credential_id?: string;
+    all_grant_types?: never;
+    [key: string]: unknown;
+} | {
+    credential_id: string;
+    grant_type?: AepGrantType;
+    all_grant_types?: never;
+    [key: string]: unknown;
+} | {
+    all_grant_types: "true";
+    credential_id?: string;
+    grant_type?: AepGrantType;
+    [key: string]: unknown;
+};
+type RevokeResponse = Record<string, never>;
+interface AepClientAssertionClaims {
+    aud: string;
+    exp: number;
+    iat: number;
+    iss: string;
+    jti: string;
+    op: AepAuthenticatedCommand;
+    sub: string;
+    [key: string]: unknown;
+}
+interface OAuthBearerGrantResponse {
+    access_token: string;
+    credential_id: string;
+    expires_at: string;
+    scopes: string[];
+    token_type: "Bearer";
+    [key: string]: unknown;
+}
+interface ApiKeyGrantResponse {
+    api_key: string;
+    credential_id: string;
+    expires_at: string;
+    header: string;
+    scopes: string[];
+    [key: string]: unknown;
+}
+interface BasicGrantResponse {
+    credential_id: string;
+    expires_at: string;
+    password: string;
+    realm?: string;
+    scopes: string[];
+    username: string;
+    [key: string]: unknown;
+}
+type AepBuiltInGrantResponse = OAuthBearerGrantResponse | ApiKeyGrantResponse | BasicGrantResponse;
+interface ValidationIssue {
+    path: string;
+    message: string;
+}
+type ValidationResult<T> = {
+    ok: true;
+    value: T;
+    issues: [];
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+};
+
+type AepJoseKey = CryptoKey | JWK | KeyObject | Uint8Array;
+type AepPemKeyFormat = "pkcs8" | "spki" | "x509";
+interface AepPemKey {
+    format: AepPemKeyFormat;
+    pem: string;
+}
+type AepImportableJoseKey = AepJoseKey | AepPemKey;
+type AepJwtVerifyKeyResolver = (protectedHeader: JWTHeaderParameters, token: FlattenedJWSInput) => AepImportableJoseKey | Promise<AepImportableJoseKey>;
+interface SignClientAssertionJwtOptions {
+    alg: AepSigningAlgorithm;
+    key: AepImportableJoseKey;
+    kid?: string;
+    typ?: string;
+}
+interface VerifyClientAssertionJwtOptions {
+    algorithms?: AepSigningAlgorithm[];
+    audience?: string;
+    clockTolerance?: JWTVerifyOptions["clockTolerance"];
+    currentDate?: Date;
+    issuer?: string;
+    key: AepImportableJoseKey | AepJwtVerifyKeyResolver;
+    subject?: string;
+}
+interface DecodedJwtParts {
+    header: Record<string, unknown>;
+    payload: Record<string, unknown>;
+}
+declare function signClientAssertionJwt(claims: AepClientAssertionClaims, options: SignClientAssertionJwtOptions): Promise<string>;
+declare function verifyClientAssertionJwt(clientAssertion: string, options: VerifyClientAssertionJwtOptions): Promise<AepClientAssertionClaims>;
+declare function importJoseKey(key: AepImportableJoseKey, alg?: string): Promise<AepJoseKey>;
+declare function importJwkJoseKey(jwk: JWK, alg?: string): Promise<AepJoseKey>;
+declare function decodeJwtUnverified(token: string): DecodedJwtParts;
+
+type DidWebFetchLike = (input: URL | string, init?: RequestInit) => Promise<Response>;
+interface ResolveDidWebPublicKeyOptions {
+    did: string;
+    fetch?: DidWebFetchLike;
+    kid?: string;
+}
+declare function didWebDocumentUrl(did: string): URL;
+declare function resolveDidWebPublicKey(options: ResolveDidWebPublicKeyOptions): Promise<AepImportableJoseKey>;
+
+declare class AepValidationError extends Error {
+    readonly issues: ValidationIssue[];
+    constructor(message: string, issues: ValidationIssue[]);
+}
+declare function createProblemDetails(input: {
+    code: AepExtensibleString<AepErrorCode>;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    type?: string;
+}): AepProblemDetails;
+
+type AepHttpCommand = Exclude<AepCommand, "inspect">;
+declare function normalizeEndpointBase(endpointBase?: string): string;
+declare function commandPath(command: AepHttpCommand, endpointBase?: string): string;
+declare function commandPathFromInspect(document: InspectDocument, command: AepHttpCommand): string;
+
+declare function validateInspectDocument(value: unknown): ValidationResult<InspectDocument>;
+declare function isInspectDocument(value: unknown): value is InspectDocument;
+declare function parseInspectDocument(value: unknown): InspectDocument;
+
+declare function validateEnrollRequest(value: unknown): ValidationResult<EnrollRequest>;
+declare function parseEnrollRequest(value: unknown): EnrollRequest;
+declare function validateEnrollResponse(value: unknown): ValidationResult<EnrollResponse>;
+declare function parseEnrollResponse(value: unknown): EnrollResponse;
+declare function validateStatusResponse(value: unknown): ValidationResult<StatusResponse>;
+declare function parseStatusResponse(value: unknown): StatusResponse;
+declare function validateGrantRequest(value: unknown): ValidationResult<GrantRequest>;
+declare function parseGrantRequest(value: unknown): GrantRequest;
+declare function validateRevokeRequest(value: unknown): ValidationResult<RevokeRequest>;
+declare function parseRevokeRequest(value: unknown): RevokeRequest;
+declare function validateRevokeResponse(value: unknown): ValidationResult<RevokeResponse>;
+declare function parseRevokeResponse(value: unknown): RevokeResponse;
+declare function validateClientAssertionClaims(value: unknown): ValidationResult<AepClientAssertionClaims>;
+declare function parseClientAssertionClaims(value: unknown): AepClientAssertionClaims;
+declare function validateProblemDetails(value: unknown): ValidationResult<AepProblemDetails>;
+declare function parseProblemDetails(value: unknown): AepProblemDetails;
+declare function validateOAuthBearerGrantResponse(value: unknown): ValidationResult<OAuthBearerGrantResponse>;
+declare function validateApiKeyGrantResponse(value: unknown): ValidationResult<ApiKeyGrantResponse>;
+declare function validateBasicGrantResponse(value: unknown): ValidationResult<BasicGrantResponse>;
+declare function validateBuiltInGrantResponse(grantType: string, value: unknown): ValidationResult<AepBuiltInGrantResponse>;
+declare function parseBuiltInGrantResponse(grantType: string, value: unknown): AepBuiltInGrantResponse;
+
+declare const inspectDocumentSchema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://www.aep.foundation/schemas/inspect-document.schema.json";
+    readonly title: "AEP Inspect Document";
+    readonly type: "object";
+    readonly required: readonly ["aep_version", "bindings", "commands", "core", "http", "identity", "service"];
+    readonly additionalProperties: true;
+    readonly properties: {
+        readonly aep_version: {
+            readonly type: "string";
+            readonly pattern: "^[0-9]+\\.[0-9]+$";
+        };
+        readonly bindings: {
+            readonly type: "object";
+            readonly required: readonly ["supported"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly supported: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly items: {
+                        readonly type: "string";
+                        readonly enum: readonly ["http"];
+                    };
+                };
+            };
+        };
+        readonly claims: {
+            readonly type: "object";
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly required: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly preferred: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly optional: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly commands: {
+            readonly type: "object";
+            readonly required: readonly ["supported"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly supported: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly items: {
+                        readonly type: "string";
+                        readonly enum: readonly ["inspect", "enroll", "grant", "revoke", "status"];
+                    };
+                };
+                readonly grant_types: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly core: {
+            readonly type: "object";
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly signing_algorithms: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly extensions: {
+            readonly type: "object";
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly supported: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly http: {
+            readonly type: "object";
+            readonly required: readonly ["endpoint_base"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly endpoint_base: {
+                    readonly type: "string";
+                    readonly pattern: "^/";
+                };
+            };
+        };
+        readonly identity: {
+            readonly type: "object";
+            readonly required: readonly ["methods"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly methods: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly items: {
+                        readonly type: "string";
+                        readonly pattern: "^[a-z0-9]+(?::[a-z0-9]+)*(?:-[a-z0-9]+)*$";
+                    };
+                };
+            };
+        };
+        readonly service: {
+            readonly type: "object";
+            readonly required: readonly ["did"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly did: {
+                    readonly type: "string";
+                    readonly pattern: "^did:";
+                };
+            };
+        };
+    };
+};
+
+export { AEP_AUTHENTICATED_COMMANDS, AEP_AUTH_SCHEME, AEP_BINDINGS, AEP_BUILT_IN_GRANT_TYPES, AEP_COMMANDS, AEP_GRANT_TYPE_API_KEY, AEP_GRANT_TYPE_BASIC, AEP_GRANT_TYPE_OAUTH_BEARER, AEP_IDENTITY_METHOD_DID_WEB, AEP_MEDIA_TYPE, AEP_PROBLEM_MEDIA_TYPE, AEP_SIGNING_ALGORITHMS, AEP_VERSION, AEP_WELL_KNOWN_PATH, type AepAgentStatus, type AepAuthenticatedCommand, type AepBinding, type AepBuiltInGrantResponse, type AepBuiltInGrantType, type AepClientAssertionClaims, type AepCommand, type AepEnrollmentStatus, type AepErrorCode, type AepExtensibleString, type AepGrantType, type AepHttpCommand, type AepIdentityMethod, type AepImportableJoseKey, type AepJoseKey, type AepJwtVerifyKeyResolver, type AepPemKey, type AepPemKeyFormat, type AepProblemDetails, type AepSigningAlgorithm, AepValidationError, type ApiKeyGrantResponse, type BasicGrantResponse, DEFAULT_HTTP_ENDPOINT_BASE, type DecodedJwtParts, type DidWebFetchLike, type EnrollRequest, type EnrollResponse, type GrantRequest, type InspectDocument, type OAuthBearerGrantResponse, type ResolveDidWebPublicKeyOptions, type RevokeRequest, type RevokeResponse, type SignClientAssertionJwtOptions, type StatusResponse, type ValidationIssue, type ValidationResult, type VerifyClientAssertionJwtOptions, commandPath, commandPathFromInspect, createProblemDetails, decodeJwtUnverified, didWebDocumentUrl, importJoseKey, importJwkJoseKey, inspectDocumentSchema, isInspectDocument, normalizeEndpointBase, parseBuiltInGrantResponse, parseClientAssertionClaims, parseEnrollRequest, parseEnrollResponse, parseGrantRequest, parseInspectDocument, parseProblemDetails, parseRevokeRequest, parseRevokeResponse, parseStatusResponse, resolveDidWebPublicKey, signClientAssertionJwt, validateApiKeyGrantResponse, validateBasicGrantResponse, validateBuiltInGrantResponse, validateClientAssertionClaims, validateEnrollRequest, validateEnrollResponse, validateGrantRequest, validateInspectDocument, validateOAuthBearerGrantResponse, validateProblemDetails, validateRevokeRequest, validateRevokeResponse, validateStatusResponse, verifyClientAssertionJwt };