@oma3/omatrust 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/types-dpYxRq8N.d.cts

@@ -0,0 +1,281 @@
+/**
+ * JWK and did:jwk Helpers — Phase 2
+ *
+ * Provides conversion between public JWKs and did:jwk DIDs,
+ * deterministic JWK comparison, and public JWK validation.
+ *
+ * did:jwk is the preferred durable DID representation for JWS/JWK public key
+ * material. It is immutable (the DID IS the key) and should be used as the
+ * controllerDid for authorization checks.
+ *
+ * Uses the `jose` library for base64url encoding/decoding and JWK thumbprints.
+ */
+/** Minimal public JWK structure */
+interface PublicJwk {
+    kty: string;
+    [key: string]: unknown;
+}
+/** Result of JWK validation */
+interface JwkValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate that a JWK object is a well-formed public key.
+ *
+ * Requirements:
+ * - Must be a non-null object
+ * - Must have a valid `kty` (EC, OKP, RSA)
+ * - Must have required public key fields for its key type
+ * - Must NOT contain private key material (d, p, q, dp, dq, qi, oth)
+ */
+declare function validatePublicJwk(jwk: unknown): JwkValidationResult;
+/**
+ * Convert a public JWK to a did:jwk DID.
+ *
+ * Uses deterministic (sorted-key) JSON serialization and base64url encoding.
+ * Rejects JWKs containing private key material.
+ *
+ * @param jwk - A public JWK object
+ * @returns The did:jwk DID string
+ * @throws OmaTrustError if the JWK is invalid or contains private key material
+ */
+declare function jwkToDidJwk(jwk: unknown): string;
+/**
+ * Convert a did:jwk DID back to a public JWK object.
+ *
+ * Validates the DID structure, decodes the base64url payload,
+ * parses JSON, and validates the resulting JWK.
+ *
+ * @param didJwk - A did:jwk DID string
+ * @returns The decoded public JWK object
+ * @throws OmaTrustError if the DID is malformed or contains private key material
+ */
+declare function didJwkToJwk(didJwk: string): PublicJwk;
+/**
+ * Compare two public JWKs for equality.
+ *
+ * Compares only the public key material fields (kty, crv, x, y, n, e, etc.).
+ * Ignores property order, metadata fields (kid, use, alg, key_ops, ext),
+ * and rejects/strips private key fields before comparison.
+ *
+ * @param a - First public JWK
+ * @param b - Second public JWK
+ * @returns true if both JWKs represent the same public key
+ * @throws OmaTrustError if either JWK contains private key material
+ */
+declare function publicJwkEquals(a: unknown, b: unknown): boolean;
+/**
+ * Compute an RFC 7638 JWK Thumbprint for a public JWK.
+ *
+ * Returns the base64url-encoded SHA-256 thumbprint. This is a compact,
+ * deterministic fingerprint of the public key material.
+ *
+ * Used in OMATrust DNS TXT records as: `jkt=S256:<thumbprint>`
+ *
+ * @param jwk - A public JWK object
+ * @param digestAlgorithm - Hash algorithm (default: "sha256")
+ * @returns base64url-encoded thumbprint string
+ * @throws OmaTrustError if the JWK is invalid or contains private key material
+ */
+declare function computeJwkThumbprint(jwk: unknown, digestAlgorithm?: "sha256" | "sha384" | "sha512"): Promise<string>;
+/**
+ * Format a JWK thumbprint as an OMATrust DNS TXT `jkt` value.
+ *
+ * Format: `jkt=S256:<base64url-thumbprint>`
+ *
+ * @param jwk - A public JWK object
+ * @returns Formatted jkt string for DNS TXT records
+ */
+declare function formatJktValue(jwk: unknown): Promise<string>;
+
+/**
+ * DID URL Key Resolution — Phase 3
+ *
+ * Resolves DID URL key references (e.g. did:web:api.example.com#key-1) to
+ * public key material and derives durable did:jwk controller DIDs.
+ *
+ * DID URLs are mutable key references. This module resolves them to the
+ * actual public key material they currently point to, then converts that
+ * material into an immutable did:jwk for use as a controller DID.
+ */
+
+/** Result of resolving a DID URL to public key material */
+interface ResolvedPublicKey {
+    /** The original DID URL */
+    didUrl: string;
+    /** The base DID (without fragment) */
+    did: string;
+    /** The fragment identifier */
+    fragment: string | null;
+    /** The resolved public JWK */
+    publicKeyJwk: PublicJwk;
+    /** The verification method ID that matched */
+    verificationMethodId: string;
+}
+/** Result of resolving a DID URL to a durable controller DID */
+interface ResolvedControllerDid extends ResolvedPublicKey {
+    /** The durable did:jwk derived from the resolved public key */
+    controllerDid: string;
+}
+/** Options for DID URL key resolution */
+interface ResolveKeyOptions {
+    /**
+     * Custom DID document fetcher. If not provided, uses the shared
+     * fetchDidDocument which fetches from `/.well-known/did.json`.
+     */
+    fetchDidDocument?: (domain: string) => Promise<Record<string, unknown>>;
+}
+/**
+ * Resolve a DID URL to public key material.
+ *
+ * Currently supports:
+ * - did:web with fragment (e.g. did:web:api.example.com#key-1)
+ *
+ * Resolution steps:
+ * 1. Parse the DID URL
+ * 2. Resolve the base DID (fetch DID document)
+ * 3. Find the matching verification method
+ * 4. Extract and validate publicKeyJwk
+ *
+ * This function only obtains key material. It does not make authorization
+ * decisions or check Controller Witness / Key Binding records.
+ *
+ * @param didUrl - A DID URL string (e.g. "did:web:api.example.com#key-1")
+ * @param options - Optional configuration (custom fetcher, etc.)
+ * @returns Resolved public key information
+ * @throws OmaTrustError if resolution fails
+ */
+declare function resolveDidUrlToPublicKey(didUrl: string, options?: ResolveKeyOptions): Promise<ResolvedPublicKey>;
+/**
+ * Resolve a DID URL to a durable controller DID.
+ *
+ * This wraps resolveDidUrlToPublicKey and adds the did:jwk conversion step.
+ * The returned controllerDid is the durable DID that callers should pass
+ * to getControllerAuthorization.
+ *
+ * @param didUrl - A DID URL string (e.g. "did:web:api.example.com#key-1")
+ * @param options - Optional configuration (custom fetcher, etc.)
+ * @returns Resolved public key plus derived did:jwk controller DID
+ * @throws OmaTrustError if resolution fails
+ */
+declare function resolveDidUrlToControllerDid(didUrl: string, options?: ResolveKeyOptions): Promise<ResolvedControllerDid>;
+
+/**
+ * Identity Types — Phase 4
+ *
+ * Types for JWS verification results and authorization metadata.
+ * These define the contract between signature verification and
+ * downstream authorization checks via getControllerAuthorization.
+ */
+
+/** Source of the public key used for JWS signature verification */
+type PublicKeySource = "embedded-jwk" | "kid-resolution";
+/**
+ * Structured result of JWS signature verification.
+ *
+ * This result is NOT an authorization result. It does not determine whether
+ * the signing key was authorized to act for the service identified by resourceUrl.
+ *
+ * It provides enough information for callers to perform downstream authorization
+ * checks via getControllerAuthorization:
+ * - publicKeyDid (did:jwk) is the durable controller DID
+ * - resourceUrl identifies the service subject
+ * - issuedAt enables authorization-window checks for receipts
+ */
+interface JwsVerificationResult {
+    /** Whether the JWS signature is cryptographically valid */
+    valid: boolean;
+    /** Decoded JWS protected header */
+    header: Record<string, unknown>;
+    /** Decoded JWS payload */
+    payload: Record<string, unknown>;
+    /** kid from the JWS header (a key reference, NOT a controller DID) */
+    kid: string | null;
+    /** The public JWK used for signature verification */
+    publicKeyJwk: PublicJwk;
+    /** How the public key was obtained */
+    publicKeySource: PublicKeySource;
+    /**
+     * The durable did:jwk derived from the public key.
+     * This is the controller DID for downstream authorization checks.
+     * Pass this as controllerDid to getControllerAuthorization.
+     */
+    publicKeyDid: string;
+    /** Error details when valid is false */
+    error?: JwsVerificationError;
+}
+/** Error details for failed JWS verification */
+interface JwsVerificationError {
+    code: string;
+    message: string;
+}
+/**
+ * Failed JWS verification result.
+ * Returned when parsing, decoding, or signature verification fails.
+ */
+interface JwsVerificationFailure {
+    valid: false;
+    error: JwsVerificationError;
+    header?: Record<string, unknown>;
+    payload?: Record<string, unknown>;
+    kid?: string | null;
+    publicKeyJwk?: PublicJwk;
+    publicKeySource?: PublicKeySource;
+    publicKeyDid?: string;
+}
+/**
+ * Authorization metadata extracted from a verified JWS artifact.
+ *
+ * This is the information a caller needs to perform an authorization check
+ * after JWS signature verification succeeds.
+ *
+ * Usage:
+ * 1. Verify JWS → get JwsVerificationResult
+ * 2. Extract AuthorizationMetadata from the result
+ * 3. Call getControllerAuthorization({ subjectDid, controllerDid, purpose })
+ * 4. Evaluate the returned authorization window against policy
+ */
+interface AuthorizationMetadata {
+    /**
+     * The durable controller DID (did:jwk) derived from the verified public key.
+     * Pass this as controllerDid to getControllerAuthorization.
+     */
+    controllerDid: string;
+    /**
+     * The subject DID derived from resourceUrl.
+     * For x402 artifacts, this is typically did:web:<domain-from-resourceUrl>.
+     * Pass this as subjectDid to getControllerAuthorization.
+     */
+    subjectDid: string | null;
+    /**
+     * The resourceUrl from the signed payload.
+     * Identifies the service/resource the artifact is associated with.
+     */
+    resourceUrl: string | null;
+    /**
+     * The issuedAt timestamp from the signed payload (receipts).
+     * Used for authorization-window checks — was the controller authorized at this time?
+     */
+    issuedAt: string | null;
+    /**
+     * The kid from the JWS header (mutable key reference).
+     * Useful for key-pinning lookups but NOT a controller DID.
+     */
+    kid: string | null;
+    /** The public JWK used for signature verification */
+    publicKeyJwk: PublicJwk;
+}
+/**
+ * Extract authorization metadata from a successful JWS verification result.
+ *
+ * Derives the subject DID from resourceUrl when possible (assumes did:web
+ * for HTTPS URLs). Returns null for subjectDid if resourceUrl is missing
+ * or cannot be parsed.
+ *
+ * @param result - A successful JwsVerificationResult (valid === true)
+ * @returns Authorization metadata for downstream getControllerAuthorization calls
+ */
+declare function extractAuthorizationMetadata(result: JwsVerificationResult): AuthorizationMetadata;
+
+export { type AuthorizationMetadata as A, type JwkValidationResult as J, type PublicJwk as P, type ResolveKeyOptions as R, type JwsVerificationError as a, type JwsVerificationFailure as b, type JwsVerificationResult as c, type PublicKeySource as d, type ResolvedControllerDid as e, type ResolvedPublicKey as f, computeJwkThumbprint as g, didJwkToJwk as h, extractAuthorizationMetadata as i, formatJktValue as j, jwkToDidJwk as k, resolveDidUrlToPublicKey as l, publicJwkEquals as p, resolveDidUrlToControllerDid as r, validatePublicJwk as v };

package/dist/types-dpYxRq8N.d.ts

@@ -0,0 +1,281 @@
+/**
+ * JWK and did:jwk Helpers — Phase 2
+ *
+ * Provides conversion between public JWKs and did:jwk DIDs,
+ * deterministic JWK comparison, and public JWK validation.
+ *
+ * did:jwk is the preferred durable DID representation for JWS/JWK public key
+ * material. It is immutable (the DID IS the key) and should be used as the
+ * controllerDid for authorization checks.
+ *
+ * Uses the `jose` library for base64url encoding/decoding and JWK thumbprints.
+ */
+/** Minimal public JWK structure */
+interface PublicJwk {
+    kty: string;
+    [key: string]: unknown;
+}
+/** Result of JWK validation */
+interface JwkValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate that a JWK object is a well-formed public key.
+ *
+ * Requirements:
+ * - Must be a non-null object
+ * - Must have a valid `kty` (EC, OKP, RSA)
+ * - Must have required public key fields for its key type
+ * - Must NOT contain private key material (d, p, q, dp, dq, qi, oth)
+ */
+declare function validatePublicJwk(jwk: unknown): JwkValidationResult;
+/**
+ * Convert a public JWK to a did:jwk DID.
+ *
+ * Uses deterministic (sorted-key) JSON serialization and base64url encoding.
+ * Rejects JWKs containing private key material.
+ *
+ * @param jwk - A public JWK object
+ * @returns The did:jwk DID string
+ * @throws OmaTrustError if the JWK is invalid or contains private key material
+ */
+declare function jwkToDidJwk(jwk: unknown): string;
+/**
+ * Convert a did:jwk DID back to a public JWK object.
+ *
+ * Validates the DID structure, decodes the base64url payload,
+ * parses JSON, and validates the resulting JWK.
+ *
+ * @param didJwk - A did:jwk DID string
+ * @returns The decoded public JWK object
+ * @throws OmaTrustError if the DID is malformed or contains private key material
+ */
+declare function didJwkToJwk(didJwk: string): PublicJwk;
+/**
+ * Compare two public JWKs for equality.
+ *
+ * Compares only the public key material fields (kty, crv, x, y, n, e, etc.).
+ * Ignores property order, metadata fields (kid, use, alg, key_ops, ext),
+ * and rejects/strips private key fields before comparison.
+ *
+ * @param a - First public JWK
+ * @param b - Second public JWK
+ * @returns true if both JWKs represent the same public key
+ * @throws OmaTrustError if either JWK contains private key material
+ */
+declare function publicJwkEquals(a: unknown, b: unknown): boolean;
+/**
+ * Compute an RFC 7638 JWK Thumbprint for a public JWK.
+ *
+ * Returns the base64url-encoded SHA-256 thumbprint. This is a compact,
+ * deterministic fingerprint of the public key material.
+ *
+ * Used in OMATrust DNS TXT records as: `jkt=S256:<thumbprint>`
+ *
+ * @param jwk - A public JWK object
+ * @param digestAlgorithm - Hash algorithm (default: "sha256")
+ * @returns base64url-encoded thumbprint string
+ * @throws OmaTrustError if the JWK is invalid or contains private key material
+ */
+declare function computeJwkThumbprint(jwk: unknown, digestAlgorithm?: "sha256" | "sha384" | "sha512"): Promise<string>;
+/**
+ * Format a JWK thumbprint as an OMATrust DNS TXT `jkt` value.
+ *
+ * Format: `jkt=S256:<base64url-thumbprint>`
+ *
+ * @param jwk - A public JWK object
+ * @returns Formatted jkt string for DNS TXT records
+ */
+declare function formatJktValue(jwk: unknown): Promise<string>;
+
+/**
+ * DID URL Key Resolution — Phase 3
+ *
+ * Resolves DID URL key references (e.g. did:web:api.example.com#key-1) to
+ * public key material and derives durable did:jwk controller DIDs.
+ *
+ * DID URLs are mutable key references. This module resolves them to the
+ * actual public key material they currently point to, then converts that
+ * material into an immutable did:jwk for use as a controller DID.
+ */
+
+/** Result of resolving a DID URL to public key material */
+interface ResolvedPublicKey {
+    /** The original DID URL */
+    didUrl: string;
+    /** The base DID (without fragment) */
+    did: string;
+    /** The fragment identifier */
+    fragment: string | null;
+    /** The resolved public JWK */
+    publicKeyJwk: PublicJwk;
+    /** The verification method ID that matched */
+    verificationMethodId: string;
+}
+/** Result of resolving a DID URL to a durable controller DID */
+interface ResolvedControllerDid extends ResolvedPublicKey {
+    /** The durable did:jwk derived from the resolved public key */
+    controllerDid: string;
+}
+/** Options for DID URL key resolution */
+interface ResolveKeyOptions {
+    /**
+     * Custom DID document fetcher. If not provided, uses the shared
+     * fetchDidDocument which fetches from `/.well-known/did.json`.
+     */
+    fetchDidDocument?: (domain: string) => Promise<Record<string, unknown>>;
+}
+/**
+ * Resolve a DID URL to public key material.
+ *
+ * Currently supports:
+ * - did:web with fragment (e.g. did:web:api.example.com#key-1)
+ *
+ * Resolution steps:
+ * 1. Parse the DID URL
+ * 2. Resolve the base DID (fetch DID document)
+ * 3. Find the matching verification method
+ * 4. Extract and validate publicKeyJwk
+ *
+ * This function only obtains key material. It does not make authorization
+ * decisions or check Controller Witness / Key Binding records.
+ *
+ * @param didUrl - A DID URL string (e.g. "did:web:api.example.com#key-1")
+ * @param options - Optional configuration (custom fetcher, etc.)
+ * @returns Resolved public key information
+ * @throws OmaTrustError if resolution fails
+ */
+declare function resolveDidUrlToPublicKey(didUrl: string, options?: ResolveKeyOptions): Promise<ResolvedPublicKey>;
+/**
+ * Resolve a DID URL to a durable controller DID.
+ *
+ * This wraps resolveDidUrlToPublicKey and adds the did:jwk conversion step.
+ * The returned controllerDid is the durable DID that callers should pass
+ * to getControllerAuthorization.
+ *
+ * @param didUrl - A DID URL string (e.g. "did:web:api.example.com#key-1")
+ * @param options - Optional configuration (custom fetcher, etc.)
+ * @returns Resolved public key plus derived did:jwk controller DID
+ * @throws OmaTrustError if resolution fails
+ */
+declare function resolveDidUrlToControllerDid(didUrl: string, options?: ResolveKeyOptions): Promise<ResolvedControllerDid>;
+
+/**
+ * Identity Types — Phase 4
+ *
+ * Types for JWS verification results and authorization metadata.
+ * These define the contract between signature verification and
+ * downstream authorization checks via getControllerAuthorization.
+ */
+
+/** Source of the public key used for JWS signature verification */
+type PublicKeySource = "embedded-jwk" | "kid-resolution";
+/**
+ * Structured result of JWS signature verification.
+ *
+ * This result is NOT an authorization result. It does not determine whether
+ * the signing key was authorized to act for the service identified by resourceUrl.
+ *
+ * It provides enough information for callers to perform downstream authorization
+ * checks via getControllerAuthorization:
+ * - publicKeyDid (did:jwk) is the durable controller DID
+ * - resourceUrl identifies the service subject
+ * - issuedAt enables authorization-window checks for receipts
+ */
+interface JwsVerificationResult {
+    /** Whether the JWS signature is cryptographically valid */
+    valid: boolean;
+    /** Decoded JWS protected header */
+    header: Record<string, unknown>;
+    /** Decoded JWS payload */
+    payload: Record<string, unknown>;
+    /** kid from the JWS header (a key reference, NOT a controller DID) */
+    kid: string | null;
+    /** The public JWK used for signature verification */
+    publicKeyJwk: PublicJwk;
+    /** How the public key was obtained */
+    publicKeySource: PublicKeySource;
+    /**
+     * The durable did:jwk derived from the public key.
+     * This is the controller DID for downstream authorization checks.
+     * Pass this as controllerDid to getControllerAuthorization.
+     */
+    publicKeyDid: string;
+    /** Error details when valid is false */
+    error?: JwsVerificationError;
+}
+/** Error details for failed JWS verification */
+interface JwsVerificationError {
+    code: string;
+    message: string;
+}
+/**
+ * Failed JWS verification result.
+ * Returned when parsing, decoding, or signature verification fails.
+ */
+interface JwsVerificationFailure {
+    valid: false;
+    error: JwsVerificationError;
+    header?: Record<string, unknown>;
+    payload?: Record<string, unknown>;
+    kid?: string | null;
+    publicKeyJwk?: PublicJwk;
+    publicKeySource?: PublicKeySource;
+    publicKeyDid?: string;
+}
+/**
+ * Authorization metadata extracted from a verified JWS artifact.
+ *
+ * This is the information a caller needs to perform an authorization check
+ * after JWS signature verification succeeds.
+ *
+ * Usage:
+ * 1. Verify JWS → get JwsVerificationResult
+ * 2. Extract AuthorizationMetadata from the result
+ * 3. Call getControllerAuthorization({ subjectDid, controllerDid, purpose })
+ * 4. Evaluate the returned authorization window against policy
+ */
+interface AuthorizationMetadata {
+    /**
+     * The durable controller DID (did:jwk) derived from the verified public key.
+     * Pass this as controllerDid to getControllerAuthorization.
+     */
+    controllerDid: string;
+    /**
+     * The subject DID derived from resourceUrl.
+     * For x402 artifacts, this is typically did:web:<domain-from-resourceUrl>.
+     * Pass this as subjectDid to getControllerAuthorization.
+     */
+    subjectDid: string | null;
+    /**
+     * The resourceUrl from the signed payload.
+     * Identifies the service/resource the artifact is associated with.
+     */
+    resourceUrl: string | null;
+    /**
+     * The issuedAt timestamp from the signed payload (receipts).
+     * Used for authorization-window checks — was the controller authorized at this time?
+     */
+    issuedAt: string | null;
+    /**
+     * The kid from the JWS header (mutable key reference).
+     * Useful for key-pinning lookups but NOT a controller DID.
+     */
+    kid: string | null;
+    /** The public JWK used for signature verification */
+    publicKeyJwk: PublicJwk;
+}
+/**
+ * Extract authorization metadata from a successful JWS verification result.
+ *
+ * Derives the subject DID from resourceUrl when possible (assumes did:web
+ * for HTTPS URLs). Returns null for subjectDid if resourceUrl is missing
+ * or cannot be parsed.
+ *
+ * @param result - A successful JwsVerificationResult (valid === true)
+ * @returns Authorization metadata for downstream getControllerAuthorization calls
+ */
+declare function extractAuthorizationMetadata(result: JwsVerificationResult): AuthorizationMetadata;
+
+export { type AuthorizationMetadata as A, type JwkValidationResult as J, type PublicJwk as P, type ResolveKeyOptions as R, type JwsVerificationError as a, type JwsVerificationFailure as b, type JwsVerificationResult as c, type PublicKeySource as d, type ResolvedControllerDid as e, type ResolvedPublicKey as f, computeJwkThumbprint as g, didJwkToJwk as h, extractAuthorizationMetadata as i, formatJktValue as j, jwkToDidJwk as k, resolveDidUrlToPublicKey as l, publicJwkEquals as p, resolveDidUrlToControllerDid as r, validatePublicJwk as v };