@mcp-i/core 0.1.0

package/dist/utils/crypto-service.js

@@ -0,0 +1,153 @@
+/**
+ * CryptoService
+ *
+ * Centralized cryptographic operations service providing consistent
+ * signature verification across all platforms (Cloudflare, Node.js, etc.).
+ */
+import { base64urlDecodeToString, base64urlDecodeToBytes, base64urlEncodeFromBytes, bytesToBase64, } from './base64.js';
+export class CryptoService {
+    cryptoProvider;
+    constructor(cryptoProvider) {
+        this.cryptoProvider = cryptoProvider;
+    }
+    async verifyEd25519(data, signature, publicKey) {
+        try {
+            const result = await this.cryptoProvider.verify(data, signature, publicKey);
+            return result === true;
+        }
+        catch (error) {
+            console.error('[CryptoService] Ed25519 verification error:', error);
+            return false;
+        }
+    }
+    parseJWS(jws) {
+        const parts = jws.split('.');
+        if (parts.length !== 3) {
+            throw new Error('Invalid JWS format: expected header.payload.signature');
+        }
+        const [headerB64, payloadB64, signatureB64] = parts;
+        let header;
+        try {
+            header = JSON.parse(base64urlDecodeToString(headerB64));
+        }
+        catch (error) {
+            throw new Error(`Invalid header base64: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        let payload;
+        if (payloadB64) {
+            try {
+                payload = JSON.parse(base64urlDecodeToString(payloadB64));
+            }
+            catch (error) {
+                throw new Error(`Invalid payload base64: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        let signatureBytes;
+        try {
+            signatureBytes = base64urlDecodeToBytes(signatureB64);
+        }
+        catch (error) {
+            throw new Error(`Invalid signature base64: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const signingInput = `${headerB64}.${payloadB64}`;
+        return { header, payload, signatureBytes, signingInput };
+    }
+    async verifyJWS(jws, publicKeyJwk, options) {
+        try {
+            if (!this.isValidEd25519JWK(publicKeyJwk)) {
+                console.error('[CryptoService] Invalid Ed25519 JWK format');
+                return false;
+            }
+            if (options?.expectedKid && publicKeyJwk.kid !== options.expectedKid) {
+                console.error('[CryptoService] Key ID mismatch');
+                return false;
+            }
+            let parsed;
+            try {
+                parsed = this.parseJWS(jws);
+            }
+            catch (error) {
+                if (options?.detachedPayload !== undefined) {
+                    const parts = jws.split('.');
+                    if (parts.length === 3 && parts[1] === '') {
+                        try {
+                            const headerB64 = parts[0];
+                            const signatureB64 = parts[2];
+                            const header = JSON.parse(base64urlDecodeToString(headerB64));
+                            const signatureBytes = base64urlDecodeToBytes(signatureB64);
+                            parsed = { header, payload: undefined, signatureBytes, signingInput: '' };
+                        }
+                        catch {
+                            console.error('[CryptoService] Invalid detached JWS format');
+                            return false;
+                        }
+                    }
+                    else {
+                        console.error('[CryptoService] Invalid JWS format:', error);
+                        return false;
+                    }
+                }
+                else {
+                    console.error('[CryptoService] Invalid JWS format:', error);
+                    return false;
+                }
+            }
+            const expectedAlg = options?.alg || 'EdDSA';
+            if (parsed.header['alg'] !== expectedAlg) {
+                console.error(`[CryptoService] Unsupported algorithm: ${parsed.header['alg']}, expected ${expectedAlg}`);
+                return false;
+            }
+            let signingInputBytes;
+            if (options?.detachedPayload !== undefined) {
+                const headerB64 = jws.split('.')[0];
+                let payloadB64;
+                if (options.detachedPayload instanceof Uint8Array) {
+                    payloadB64 = base64urlEncodeFromBytes(options.detachedPayload);
+                }
+                else {
+                    payloadB64 = base64urlEncodeFromBytes(new TextEncoder().encode(options.detachedPayload));
+                }
+                signingInputBytes = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+            }
+            else {
+                if (!parsed.signingInput) {
+                    console.error('[CryptoService] Missing signing input for compact JWS');
+                    return false;
+                }
+                signingInputBytes = new TextEncoder().encode(parsed.signingInput);
+            }
+            let publicKeyBase64;
+            try {
+                publicKeyBase64 = this.jwkToBase64PublicKey(publicKeyJwk);
+            }
+            catch (error) {
+                console.error('[CryptoService] Failed to extract public key:', error);
+                return false;
+            }
+            return await this.verifyEd25519(signingInputBytes, parsed.signatureBytes, publicKeyBase64);
+        }
+        catch (error) {
+            console.error('[CryptoService] JWS verification error:', error);
+            return false;
+        }
+    }
+    isValidEd25519JWK(jwk) {
+        return (typeof jwk === 'object' &&
+            jwk !== null &&
+            'kty' in jwk &&
+            jwk['kty'] === 'OKP' &&
+            'crv' in jwk &&
+            jwk['crv'] === 'Ed25519' &&
+            'x' in jwk &&
+            typeof jwk['x'] === 'string' &&
+            jwk['x'].length > 0);
+    }
+    jwkToBase64PublicKey(jwk) {
+        const publicKeyBytes = base64urlDecodeToBytes(jwk.x);
+        if (publicKeyBytes.length !== 32) {
+            throw new Error(`Invalid Ed25519 public key length: ${publicKeyBytes.length}`);
+        }
+        return bytesToBase64(publicKeyBytes);
+    }
+}
+//# sourceMappingURL=crypto-service.js.map

package/dist/utils/crypto-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto-service.js","sourceRoot":"","sources":["../../src/utils/crypto-service.ts"],"names":[],"mappings":"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"}

package/dist/utils/did-helpers.d.ts

@@ -0,0 +1,156 @@
+/**
+ * DID Validation and Helper Utilities
+ *
+ * Centralized utilities for DID validation, normalization, and handling.
+ * Promotes DRY principle and consistency across the codebase.
+ *
+ * @package @mcp-i/core/utils
+ */
+/**
+ * Check if a string is a valid DID format
+ *
+ * @param did - String to validate
+ * @returns true if string starts with "did:"
+ *
+ * @example
+ * ```typescript
+ * isValidDid("did:key:z6Mk...") // true
+ * isValidDid("not-a-did") // false
+ * ```
+ */
+export declare function isValidDid(did: string): boolean;
+/**
+ * Get the DID method from a DID string
+ *
+ * @param did - DID string
+ * @returns DID method (e.g., "key", "web") or null if invalid
+ *
+ * @example
+ * ```typescript
+ * getDidMethod("did:key:z6Mk...") // "key"
+ * getDidMethod("did:web:example.com") // "web"
+ * getDidMethod("invalid") // null
+ * ```
+ */
+export declare function getDidMethod(did: string): string | null;
+/**
+ * Normalize a DID string (trim whitespace)
+ *
+ * @param did - DID string to normalize
+ * @returns Normalized DID string
+ *
+ * @example
+ * ```typescript
+ * normalizeDid("  did:key:z6Mk...  ") // "did:key:z6Mk..."
+ * ```
+ */
+export declare function normalizeDid(did: string): string;
+/**
+ * Compare two DIDs for equality (case-sensitive)
+ *
+ * @param did1 - First DID
+ * @param did2 - Second DID
+ * @returns true if DIDs are equal (after normalization)
+ *
+ * @example
+ * ```typescript
+ * compareDids("did:key:z6Mk...", "did:key:z6Mk...") // true
+ * compareDids("did:key:z6Mk...", "did:web:example.com") // false
+ * ```
+ */
+export declare function compareDids(did1: string, did2: string): boolean;
+/**
+ * Extract server DID from config (supports both old and new field names)
+ *
+ * Supports backward compatibility by reading both `serverDid` and deprecated `agentDid`.
+ * Prefers `serverDid` if both are present.
+ *
+ * @param config - Config object with identity field
+ * @returns Server DID string
+ * @throws Error if neither serverDid nor agentDid is configured
+ *
+ * @example
+ * ```typescript
+ * // New config
+ * getServerDid({ identity: { serverDid: "did:web:example.com" } }) // "did:web:example.com"
+ *
+ * // Old config (backward compatibility)
+ * getServerDid({ identity: { agentDid: "did:web:example.com" } }) // "did:web:example.com"
+ *
+ * // Prefers serverDid over agentDid
+ * getServerDid({ identity: { serverDid: "new", agentDid: "old" } }) // "new"
+ * ```
+ */
+export declare function getServerDid(config: {
+    identity: {
+        serverDid?: string;
+        agentDid?: string;
+    };
+}): string;
+/**
+ * Extract agent ID from DID
+ *
+ * The agent ID is the last component of the DID.
+ *
+ * @param did - DID string
+ * @returns Agent ID (last component of DID)
+ *
+ * @example
+ * ```typescript
+ * extractAgentId("did:web:example.com:agents:my-agent") // "my-agent"
+ * extractAgentId("did:web:localhost:3000:agents:12912feb") // "12912feb"
+ * extractAgentId("did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK") // "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+ * ```
+ */
+export declare function extractAgentId(did: string): string;
+/**
+ * Extract agent slug from DID
+ *
+ * Agent slug is the same as agent ID - the last component of the DID.
+ * For DID format: did:web:example.com:agents:my-agent
+ * Returns: my-agent
+ *
+ * @param did - DID string
+ * @returns Agent slug (last component of DID)
+ *
+ * @example
+ * ```typescript
+ * extractAgentSlug("did:web:example.com:agents:my-agent") // "my-agent"
+ * extractAgentSlug("did:web:localhost:3000:agents:12912feb") // "12912feb"
+ * ```
+ */
+export declare function extractAgentSlug(did: string): string;
+/**
+ * Generate a did:key from Ed25519 public key bytes
+ *
+ * Following spec: https://w3c-ccg.github.io/did-method-key/
+ * Format: did:key:z<multibase-base58btc(<multicodec-ed25519-pub><publicKey>)>
+ *
+ * @param publicKeyBytes - Ed25519 public key as Uint8Array (32 bytes)
+ * @returns did:key string
+ *
+ * @example
+ * ```typescript
+ * const publicKey = new Uint8Array(32); // 32-byte Ed25519 public key
+ * const did = generateDidKeyFromBytes(publicKey);
+ * // did = "did:key:z6Mk..."
+ * ```
+ */
+export declare function generateDidKeyFromBytes(publicKeyBytes: Uint8Array): string;
+/**
+ * Generate a did:key from base64-encoded Ed25519 public key
+ *
+ * Convenience wrapper around generateDidKeyFromBytes for base64-encoded keys.
+ *
+ * @param publicKeyBase64 - Ed25519 public key as base64 string
+ * @returns did:key string
+ *
+ * @example
+ * ```typescript
+ * const publicKeyBase64 = "...base64 encoded key...";
+ * const did = generateDidKeyFromBase64(publicKeyBase64);
+ * // did = "did:key:z6Mk..."
+ * ```
+ */
+export declare function generateDidKeyFromBase64(publicKeyBase64: string): string;
+//# sourceMappingURL=did-helpers.d.ts.map

package/dist/utils/did-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"did-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/did-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IACnC,QAAQ,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD,GAAG,MAAM,CAMT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAQD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,UAAU,GAAG,MAAM,CAW1E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAMxE"}

package/dist/utils/did-helpers.js

@@ -0,0 +1,193 @@
+/**
+ * DID Validation and Helper Utilities
+ *
+ * Centralized utilities for DID validation, normalization, and handling.
+ * Promotes DRY principle and consistency across the codebase.
+ *
+ * @package @mcp-i/core/utils
+ */
+import { base58Encode } from "./base58.js";
+/**
+ * Check if a string is a valid DID format
+ *
+ * @param did - String to validate
+ * @returns true if string starts with "did:"
+ *
+ * @example
+ * ```typescript
+ * isValidDid("did:key:z6Mk...") // true
+ * isValidDid("not-a-did") // false
+ * ```
+ */
+export function isValidDid(did) {
+    return typeof did === "string" && did.startsWith("did:");
+}
+/**
+ * Get the DID method from a DID string
+ *
+ * @param did - DID string
+ * @returns DID method (e.g., "key", "web") or null if invalid
+ *
+ * @example
+ * ```typescript
+ * getDidMethod("did:key:z6Mk...") // "key"
+ * getDidMethod("did:web:example.com") // "web"
+ * getDidMethod("invalid") // null
+ * ```
+ */
+export function getDidMethod(did) {
+    if (!isValidDid(did)) {
+        return null;
+    }
+    const match = did.match(/^did:([^:]+):/);
+    return match?.[1] ?? null;
+}
+/**
+ * Normalize a DID string (trim whitespace)
+ *
+ * @param did - DID string to normalize
+ * @returns Normalized DID string
+ *
+ * @example
+ * ```typescript
+ * normalizeDid("  did:key:z6Mk...  ") // "did:key:z6Mk..."
+ * ```
+ */
+export function normalizeDid(did) {
+    return did.trim();
+}
+/**
+ * Compare two DIDs for equality (case-sensitive)
+ *
+ * @param did1 - First DID
+ * @param did2 - Second DID
+ * @returns true if DIDs are equal (after normalization)
+ *
+ * @example
+ * ```typescript
+ * compareDids("did:key:z6Mk...", "did:key:z6Mk...") // true
+ * compareDids("did:key:z6Mk...", "did:web:example.com") // false
+ * ```
+ */
+export function compareDids(did1, did2) {
+    return normalizeDid(did1) === normalizeDid(did2);
+}
+/**
+ * Extract server DID from config (supports both old and new field names)
+ *
+ * Supports backward compatibility by reading both `serverDid` and deprecated `agentDid`.
+ * Prefers `serverDid` if both are present.
+ *
+ * @param config - Config object with identity field
+ * @returns Server DID string
+ * @throws Error if neither serverDid nor agentDid is configured
+ *
+ * @example
+ * ```typescript
+ * // New config
+ * getServerDid({ identity: { serverDid: "did:web:example.com" } }) // "did:web:example.com"
+ *
+ * // Old config (backward compatibility)
+ * getServerDid({ identity: { agentDid: "did:web:example.com" } }) // "did:web:example.com"
+ *
+ * // Prefers serverDid over agentDid
+ * getServerDid({ identity: { serverDid: "new", agentDid: "old" } }) // "new"
+ * ```
+ */
+export function getServerDid(config) {
+    const serverDid = config.identity.serverDid || config.identity.agentDid;
+    if (!serverDid) {
+        throw new Error("Server DID not configured");
+    }
+    return serverDid;
+}
+/**
+ * Extract agent ID from DID
+ *
+ * The agent ID is the last component of the DID.
+ *
+ * @param did - DID string
+ * @returns Agent ID (last component of DID)
+ *
+ * @example
+ * ```typescript
+ * extractAgentId("did:web:example.com:agents:my-agent") // "my-agent"
+ * extractAgentId("did:web:localhost:3000:agents:12912feb") // "12912feb"
+ * extractAgentId("did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK") // "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+ * ```
+ */
+export function extractAgentId(did) {
+    const parts = did.split(':');
+    // split() always returns at least one element
+    return parts[parts.length - 1] ?? did;
+}
+/**
+ * Extract agent slug from DID
+ *
+ * Agent slug is the same as agent ID - the last component of the DID.
+ * For DID format: did:web:example.com:agents:my-agent
+ * Returns: my-agent
+ *
+ * @param did - DID string
+ * @returns Agent slug (last component of DID)
+ *
+ * @example
+ * ```typescript
+ * extractAgentSlug("did:web:example.com:agents:my-agent") // "my-agent"
+ * extractAgentSlug("did:web:localhost:3000:agents:12912feb") // "12912feb"
+ * ```
+ */
+export function extractAgentSlug(did) {
+    return extractAgentId(did);
+}
+/**
+ * Ed25519 multicodec prefix for did:key encoding
+ * As per https://w3c-ccg.github.io/did-method-key/
+ */
+const ED25519_MULTICODEC_PREFIX = new Uint8Array([0xed, 0x01]);
+/**
+ * Generate a did:key from Ed25519 public key bytes
+ *
+ * Following spec: https://w3c-ccg.github.io/did-method-key/
+ * Format: did:key:z<multibase-base58btc(<multicodec-ed25519-pub><publicKey>)>
+ *
+ * @param publicKeyBytes - Ed25519 public key as Uint8Array (32 bytes)
+ * @returns did:key string
+ *
+ * @example
+ * ```typescript
+ * const publicKey = new Uint8Array(32); // 32-byte Ed25519 public key
+ * const did = generateDidKeyFromBytes(publicKey);
+ * // did = "did:key:z6Mk..."
+ * ```
+ */
+export function generateDidKeyFromBytes(publicKeyBytes) {
+    // Combine multicodec prefix + public key
+    const multicodecKey = new Uint8Array(ED25519_MULTICODEC_PREFIX.length + publicKeyBytes.length);
+    multicodecKey.set(ED25519_MULTICODEC_PREFIX);
+    multicodecKey.set(publicKeyBytes, ED25519_MULTICODEC_PREFIX.length);
+    // Base58-btc encode and add multibase prefix 'z'
+    const base58Encoded = base58Encode(multicodecKey);
+    return `did:key:z${base58Encoded}`;
+}
+/**
+ * Generate a did:key from base64-encoded Ed25519 public key
+ *
+ * Convenience wrapper around generateDidKeyFromBytes for base64-encoded keys.
+ *
+ * @param publicKeyBase64 - Ed25519 public key as base64 string
+ * @returns did:key string
+ *
+ * @example
+ * ```typescript
+ * const publicKeyBase64 = "...base64 encoded key...";
+ * const did = generateDidKeyFromBase64(publicKeyBase64);
+ * // did = "did:key:z6Mk..."
+ * ```
+ */
+export function generateDidKeyFromBase64(publicKeyBase64) {
+    // Decode base64 to bytes
+    const publicKeyBytes = Uint8Array.from(atob(publicKeyBase64), (c) => c.charCodeAt(0));
+    return generateDidKeyFromBytes(publicKeyBytes);
+}
+//# sourceMappingURL=did-helpers.js.map

package/dist/utils/did-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"did-helpers.js","sourceRoot":"","sources":["../../src/utils/did-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IACzC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACpB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,IAAY;IACpD,OAAO,YAAY,CAAC,IAAI,CAAC,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAAC,MAE5B;IACC,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;IACxE,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,8CAA8C;IAC9C,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,yBAAyB,GAAG,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB,CAAC,cAA0B;IAChE,yCAAyC;IACzC,MAAM,aAAa,GAAG,IAAI,UAAU,CAClC,yBAAyB,CAAC,MAAM,GAAG,cAAc,CAAC,MAAM,CACzD,CAAC;IACF,aAAa,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IAC7C,aAAa,CAAC,GAAG,CAAC,cAAc,EAAE,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAEpE,iDAAiD;IACjD,MAAM,aAAa,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;IAClD,OAAO,YAAY,aAAa,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CAAC,eAAuB;IAC9D,yBAAyB;IACzB,MAAM,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAClE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAChB,CAAC;IACF,OAAO,uBAAuB,CAAC,cAAc,CAAC,CAAC;AACjD,CAAC"}

package/dist/utils/ed25519-constants.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Ed25519 Key Format Constants
+ *
+ * DER-encoded headers for Ed25519 key formats per RFC 8410 and RFC 5958.
+ */
+/**
+ * DER-encoded PKCS#8 header for Ed25519 private keys (RFC 8410 §7, RFC 5958).
+ * Prepended to the 32-byte Ed25519 seed to form a valid PKCS#8 private key.
+ */
+export declare const ED25519_PKCS8_DER_HEADER: Uint8Array<ArrayBuffer>;
+/**
+ * DER-encoded SPKI header for Ed25519 public keys (RFC 8410 §4).
+ * The 32-byte public key follows after this header.
+ */
+export declare const ED25519_SPKI_DER_HEADER_LENGTH = 12;
+/** Ed25519 raw key size in bytes */
+export declare const ED25519_KEY_SIZE = 32;
+//# sourceMappingURL=ed25519-constants.d.ts.map

package/dist/utils/ed25519-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ed25519-constants.d.ts","sourceRoot":"","sources":["../../src/utils/ed25519-constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,eAAO,MAAM,wBAAwB,yBAGnC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD,oCAAoC;AACpC,eAAO,MAAM,gBAAgB,KAAK,CAAC"}

package/dist/utils/ed25519-constants.js

@@ -0,0 +1,21 @@
+/**
+ * Ed25519 Key Format Constants
+ *
+ * DER-encoded headers for Ed25519 key formats per RFC 8410 and RFC 5958.
+ */
+/**
+ * DER-encoded PKCS#8 header for Ed25519 private keys (RFC 8410 §7, RFC 5958).
+ * Prepended to the 32-byte Ed25519 seed to form a valid PKCS#8 private key.
+ */
+export const ED25519_PKCS8_DER_HEADER = new Uint8Array([
+    0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05,
+    0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+]);
+/**
+ * DER-encoded SPKI header for Ed25519 public keys (RFC 8410 §4).
+ * The 32-byte public key follows after this header.
+ */
+export const ED25519_SPKI_DER_HEADER_LENGTH = 12;
+/** Ed25519 raw key size in bytes */
+export const ED25519_KEY_SIZE = 32;
+//# sourceMappingURL=ed25519-constants.js.map

package/dist/utils/ed25519-constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ed25519-constants.js","sourceRoot":"","sources":["../../src/utils/ed25519-constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,UAAU,CAAC;IACrD,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IACxC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;CACrD,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,CAAC;AAEjD,oCAAoC;AACpC,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Utility exports
+ */
+export { ED25519_PKCS8_DER_HEADER, ED25519_SPKI_DER_HEADER_LENGTH, ED25519_KEY_SIZE, } from './ed25519-constants.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,wBAAwB,EACxB,8BAA8B,EAC9B,gBAAgB,GACjB,MAAM,wBAAwB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,5 @@
+/**
+ * Utility exports
+ */
+export { ED25519_PKCS8_DER_HEADER, ED25519_SPKI_DER_HEADER_LENGTH, ED25519_KEY_SIZE, } from './ed25519-constants.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,wBAAwB,EACxB,8BAA8B,EAC9B,gBAAgB,GACjB,MAAM,wBAAwB,CAAC"}