gdc-common-utils-ts 2.0.18 → 2.1.0

package/dist/utils/profile-outbox-memory-repository.js

@@ -0,0 +1,57 @@
+// Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * In-memory profile outbox repository used by low-level tests and as the
+ * default history/response store for `ProfileManagerMem`.
+ */
+export class MemoryProfileOutboxRepository {
+    messages = new Map();
+    responses = new Map();
+    /**
+     * Stores one immutable message history record.
+     */
+    async putMessage(record) {
+        this.messages.set(record.id, clone(record));
+        return clone(record);
+    }
+    /**
+     * Reads one message history record.
+     */
+    async getMessage(messageId) {
+        const stored = this.messages.get(String(messageId || '').trim());
+        return stored ? clone(stored) : undefined;
+    }
+    /**
+     * Lists all message history records in insertion order.
+     */
+    async listMessages() {
+        return [...this.messages.values()].map((record) => clone(record));
+    }
+    /**
+     * Stores one decoded response record grouped by thread id.
+     */
+    async putResponse(record) {
+        const normalizedThreadId = String(record.thid || '').trim();
+        const current = this.responses.get(normalizedThreadId) || [];
+        current.push(clone(record));
+        this.responses.set(normalizedThreadId, current);
+        return clone(record);
+    }
+    /**
+     * Returns the latest decoded response for the provided thread id.
+     */
+    async getLatestResponseByThreadId(thid) {
+        const stored = this.responses.get(String(thid || '').trim());
+        const latest = stored?.[stored.length - 1];
+        return latest ? clone(latest) : undefined;
+    }
+    /**
+     * Lists all decoded responses across all threads.
+     */
+    async listResponses() {
+        return [...this.responses.values()]
+            .flatMap((records) => records.map((record) => clone(record)));
+    }
+}

package/dist/utils/wallet-mem.d.ts

@@ -0,0 +1,93 @@
+import { CryptographyService } from '../CryptographyService';
+import type { ICryptoHelper } from '../interfaces/ICryptoHelper';
+import type { IWallet } from '../interfaces/IWallet';
+import type { IWalletQueue } from '../interfaces/IWalletQueue';
+import type { JWK, JwkSet } from '../models/jwk';
+import { type WalletEnqueueMessageInput, type WalletManagedEntityDescriptor, type WalletQueuedMessage } from '../models/wallet';
+export type WalletMemOptions = Readonly<{
+    cryptoHelper: ICryptoHelper;
+    cryptography?: CryptographyService;
+    queue?: IWalletQueue;
+}>;
+/**
+ * In-memory wallet implementation intended for:
+ * - common low-level tests
+ * - GW template integration tests
+ * - frontend-like and BFF-like local transport simulations
+ *
+ * Design rule:
+ * - keep this class below actor-specific SDK facades
+ * - compose cryptography, key cache, local queue, and DIDComm-style
+ *   pack/unpack in one portable runtime-neutral helper
+ */
+export declare class WalletMem implements IWallet {
+    private readonly cryptoHelper;
+    private readonly cryptography;
+    private readonly entities;
+    private readonly queue;
+    constructor(options: WalletMemOptions);
+    /**
+     * Computes one digest through the injected platform helper.
+     */
+    digest(data: string, algorithm: string): Promise<string>;
+    /**
+     * Provisions one deterministic signing key, one deterministic encryption key,
+     * and one deterministic storage key for the provided entity id.
+     */
+    provisionKeys(entityId: string): Promise<JwkSet>;
+    /**
+     * Returns the public signing/encryption keys currently provisioned for one entity.
+     */
+    getPublicKeys(entityId: string): Promise<WalletManagedEntityDescriptor>;
+    /**
+     * Protects one document in memory using the entity-specific at-rest key.
+     */
+    protectConfidentialData(doc: unknown, entityId?: string): Promise<unknown>;
+    /**
+     * Unprotects one document previously encrypted through `protectConfidentialData(...)`.
+     */
+    unprotectConfidentialData(doc: unknown, entityId?: string): Promise<unknown>;
+    /**
+     * Signs one JSON payload into a compact JWS carrying the sender public JWK.
+     */
+    signCompactJws(entityId: string, claims: Record<string, unknown>): Promise<string>;
+    /**
+     * Encrypts one plaintext for the provided recipient public JWK.
+     */
+    buildCompactJwe(entityId: string, plaintext: string | Uint8Array, recipientJwk: JWK, contentType?: string): Promise<string>;
+    /**
+     * Packs one payload as nested compact JWS inside compact JWE.
+     */
+    pack(content: Record<string, unknown>, recipientJwk: JWK, entityId: string): Promise<string>;
+    /**
+     * Unpacks one compact JWE and, when present, verifies the nested compact JWS.
+     */
+    unpack(packedMessage: string, entityId?: string): Promise<{
+        content: unknown;
+        meta: Record<string, unknown>;
+    }>;
+    /**
+     * Enqueues one message in the local in-memory outbox/queue.
+     */
+    enqueueMessage(input: WalletEnqueueMessageInput): Promise<WalletQueuedMessage>;
+    /**
+     * Returns the highest-priority pending message without mutating queue state.
+     */
+    peekNextMessage(): Promise<WalletQueuedMessage | undefined>;
+    /**
+     * Marks one queued message as delivered.
+     */
+    markMessageDelivered(messageId: string): Promise<WalletQueuedMessage>;
+    /**
+     * Marks one queued message as failed while preserving it in the local queue.
+     */
+    markMessageFailed(messageId: string, errorMessage: string): Promise<WalletQueuedMessage>;
+    /**
+     * Lists all queued messages in priority/FIFO processing order.
+     */
+    listMessages(): Promise<WalletQueuedMessage[]>;
+    private deriveSeedBytes;
+    private requireEntityId;
+    private resolveEntityId;
+    private requireEntityState;
+}

package/dist/utils/wallet-mem.js

@@ -0,0 +1,277 @@
+// Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+import { CryptographyService } from '../CryptographyService.js';
+import { WalletQueueStatuses } from '../models/wallet.js';
+import { Content } from './content.js';
+import { MemoryWalletQueue } from './wallet-memory-queue.js';
+const WALLET_DIGEST_ALGORITHM = 'SHA-512';
+const WALLET_SIGNING_ALGORITHM = 'ML-DSA-44';
+const WALLET_ENCRYPTION_ALGORITHM = 'ML-KEM-768';
+const WALLET_JWE_CONTENT_ENCRYPTION = 'A256GCM';
+const WALLET_JWS_TYPE = 'JWS';
+const WALLET_JWE_TYPE = 'JWE';
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * In-memory wallet implementation intended for:
+ * - common low-level tests
+ * - GW template integration tests
+ * - frontend-like and BFF-like local transport simulations
+ *
+ * Design rule:
+ * - keep this class below actor-specific SDK facades
+ * - compose cryptography, key cache, local queue, and DIDComm-style
+ *   pack/unpack in one portable runtime-neutral helper
+ */
+export class WalletMem {
+    cryptoHelper;
+    cryptography;
+    entities = new Map();
+    queue;
+    constructor(options) {
+        this.cryptoHelper = options.cryptoHelper;
+        this.cryptography = options.cryptography ?? new CryptographyService(this.cryptoHelper);
+        this.queue = options.queue ?? new MemoryWalletQueue(this.cryptoHelper);
+    }
+    /**
+     * Computes one digest through the injected platform helper.
+     */
+    async digest(data, algorithm) {
+        return this.cryptoHelper.digestString(data, algorithm);
+    }
+    /**
+     * Provisions one deterministic signing key, one deterministic encryption key,
+     * and one deterministic storage key for the provided entity id.
+     */
+    async provisionKeys(entityId) {
+        const normalizedEntityId = this.requireEntityId(entityId);
+        const existing = this.entities.get(normalizedEntityId);
+        if (existing) {
+            return {
+                keys: [
+                    existing.descriptor.signingJwk,
+                    existing.descriptor.encryptionJwk,
+                ],
+            };
+        }
+        const signingSeed = await this.deriveSeedBytes(normalizedEntityId, 'signing', 32);
+        const encryptionSeed = await this.deriveSeedBytes(normalizedEntityId, 'encryption', 64);
+        const storageKeyBytes = await this.deriveSeedBytes(normalizedEntityId, 'storage', 32);
+        const signingKeyPair = await this.cryptography.generateKeyPairMlDsa(signingSeed, WALLET_SIGNING_ALGORITHM);
+        const encryptionKeyPair = await this.cryptography.generateKeyPairMlKem(encryptionSeed, WALLET_ENCRYPTION_ALGORITHM);
+        const descriptor = {
+            entityId: normalizedEntityId,
+            signingJwk: {
+                ...signingKeyPair.publicJWKey,
+                use: 'sig',
+            },
+            encryptionJwk: {
+                ...encryptionKeyPair.publicJWKey,
+                use: 'enc',
+            },
+        };
+        this.entities.set(normalizedEntityId, {
+            descriptor,
+            signingSecretKeyBytes: signingKeyPair.secretKeyBytes,
+            encryptionSecretKeyBytes: encryptionKeyPair.secretKeyBytes,
+            storageKeyBytes,
+        });
+        return {
+            keys: [descriptor.signingJwk, descriptor.encryptionJwk],
+        };
+    }
+    /**
+     * Returns the public signing/encryption keys currently provisioned for one entity.
+     */
+    async getPublicKeys(entityId) {
+        const state = this.requireEntityState(entityId);
+        return clone(state.descriptor);
+    }
+    /**
+     * Protects one document in memory using the entity-specific at-rest key.
+     */
+    async protectConfidentialData(doc, entityId) {
+        const document = doc;
+        if (document?.content === undefined) {
+            return doc;
+        }
+        const state = this.requireEntityState(this.resolveEntityId(entityId));
+        const ownerId = state.descriptor.entityId;
+        const encrypted = await this.cryptography.encrypt(JSON.stringify(document.content), state.storageKeyBytes, ownerId);
+        const { content, ...docWithoutContent } = document;
+        return {
+            ...docWithoutContent,
+            jwe: encrypted,
+        };
+    }
+    /**
+     * Unprotects one document previously encrypted through `protectConfidentialData(...)`.
+     */
+    async unprotectConfidentialData(doc, entityId) {
+        const document = doc;
+        if (document?.jwe === undefined) {
+            return doc;
+        }
+        const state = this.requireEntityState(this.resolveEntityId(entityId));
+        const ownerId = state.descriptor.entityId;
+        const decrypted = await this.cryptography.decrypt(document.jwe, state.storageKeyBytes, ownerId);
+        const { jwe, ...docWithoutJwe } = document;
+        return {
+            ...docWithoutJwe,
+            content: JSON.parse(decrypted),
+        };
+    }
+    /**
+     * Signs one JSON payload into a compact JWS carrying the sender public JWK.
+     */
+    async signCompactJws(entityId, claims) {
+        const state = this.requireEntityState(entityId);
+        const jws = await this.cryptography.signDataJws(claims, {
+            alg: WALLET_SIGNING_ALGORITHM,
+            typ: WALLET_JWS_TYPE,
+            kid: state.descriptor.signingJwk.kid,
+            jwk: state.descriptor.signingJwk,
+        }, state.signingSecretKeyBytes);
+        return `${jws.protected}.${jws.payload}.${jws.signature}`;
+    }
+    /**
+     * Encrypts one plaintext for the provided recipient public JWK.
+     */
+    async buildCompactJwe(entityId, plaintext, recipientJwk, contentType) {
+        const state = this.requireEntityState(entityId);
+        const senderPrivateKey = {
+            ...state.descriptor.encryptionJwk,
+            dBytes: state.encryptionSecretKeyBytes,
+        };
+        return this.cryptography.encryptJweToCompact(typeof plaintext === 'string' ? plaintext : Content.bytesToStringUTF8(plaintext), {
+            enc: WALLET_JWE_CONTENT_ENCRYPTION,
+            typ: WALLET_JWE_TYPE,
+            ...(contentType ? { cty: contentType } : {}),
+        }, senderPrivateKey, recipientJwk);
+    }
+    /**
+     * Packs one payload as nested compact JWS inside compact JWE.
+     */
+    async pack(content, recipientJwk, entityId) {
+        const compactJws = await this.signCompactJws(entityId, content);
+        return this.buildCompactJwe(entityId, compactJws, recipientJwk, WALLET_JWS_TYPE);
+    }
+    /**
+     * Unpacks one compact JWE and, when present, verifies the nested compact JWS.
+     */
+    async unpack(packedMessage, entityId) {
+        const state = this.requireEntityState(this.resolveEntityId(entityId));
+        const recipientPrivateKey = {
+            ...state.descriptor.encryptionJwk,
+            dBytes: state.encryptionSecretKeyBytes,
+        };
+        const decrypted = await this.cryptography.decryptJwe(packedMessage, recipientPrivateKey);
+        const decryptedText = Content.bytesToStringUTF8(decrypted.decryptedBytes);
+        const metadata = {
+            jwe: {
+                header: decrypted.protectedHeader,
+            },
+        };
+        if (decrypted.protectedHeader['cty'] === WALLET_JWS_TYPE) {
+            const parsedJws = this.cryptography.parseCompactJws(decryptedText);
+            const protectedHeader = parsedJws.protected;
+            const publicJwk = protectedHeader['jwk'];
+            const verified = publicJwk
+                ? await this.cryptography.verifyJws(decryptedText, publicJwk)
+                : false;
+            metadata.jws = {
+                protected: protectedHeader,
+                signature: typeof parsedJws.signature === 'string'
+                    ? parsedJws.signature
+                    : parsedJws.signature
+                        ? Content.bytesToRawBase64UrlSafe(parsedJws.signature)
+                        : '',
+            };
+            return {
+                content: parsedJws.payload,
+                meta: {
+                    ...metadata,
+                    jws: {
+                        ...metadata.jws,
+                        verified,
+                    },
+                },
+            };
+        }
+        return {
+            content: JSON.parse(decryptedText),
+            meta: metadata,
+        };
+    }
+    /**
+     * Enqueues one message in the local in-memory outbox/queue.
+     */
+    async enqueueMessage(input) {
+        return this.queue.enqueue(input);
+    }
+    /**
+     * Returns the highest-priority pending message without mutating queue state.
+     */
+    async peekNextMessage() {
+        return this.queue.peekNextPending();
+    }
+    /**
+     * Marks one queued message as delivered.
+     */
+    async markMessageDelivered(messageId) {
+        return this.queue.update(messageId, {
+            status: WalletQueueStatuses.Delivered,
+            deliveredAt: new Date().toISOString(),
+            errorMessage: undefined,
+        });
+    }
+    /**
+     * Marks one queued message as failed while preserving it in the local queue.
+     */
+    async markMessageFailed(messageId, errorMessage) {
+        return this.queue.update(messageId, {
+            status: WalletQueueStatuses.Failed,
+            errorMessage: String(errorMessage || '').trim(),
+        });
+    }
+    /**
+     * Lists all queued messages in priority/FIFO processing order.
+     */
+    async listMessages() {
+        return this.queue.list();
+    }
+    async deriveSeedBytes(entityId, purpose, size) {
+        const blocks = [];
+        let counter = 0;
+        while (Buffer.concat(blocks).length < size) {
+            const digest = await this.digest(`${entityId}:${purpose}:${counter}`, WALLET_DIGEST_ALGORITHM);
+            blocks.push(Buffer.from(digest, 'hex'));
+            counter += 1;
+        }
+        return Buffer.concat(blocks).subarray(0, size);
+    }
+    requireEntityId(entityId) {
+        const normalized = String(entityId || '').trim();
+        if (!normalized) {
+            throw new Error('WalletMem requires a non-empty entityId.');
+        }
+        return normalized;
+    }
+    resolveEntityId(entityId) {
+        if (entityId) {
+            return this.requireEntityId(entityId);
+        }
+        if (this.entities.size === 1) {
+            return [...this.entities.keys()][0];
+        }
+        throw new Error('WalletMem requires entityId when more than one entity is provisioned.');
+    }
+    requireEntityState(entityId) {
+        const normalized = this.requireEntityId(entityId);
+        const state = this.entities.get(normalized);
+        if (!state) {
+            throw new Error(`WalletMem requires provisionKeys('${normalized}') before this operation.`);
+        }
+        return state;
+    }
+}

package/dist/utils/wallet-memory-queue.d.ts

@@ -0,0 +1,32 @@
+import type { ICryptoHelper } from '../interfaces/ICryptoHelper';
+import type { IWalletQueue } from '../interfaces/IWalletQueue';
+import { type WalletEnqueueMessageInput, type WalletQueuedMessage } from '../models/wallet';
+/**
+ * Default in-memory queue/outbox implementation for `WalletMem`.
+ *
+ * Contract:
+ * - `emergency` outranks `high`, `normal`, and `low`
+ * - within the same priority level, FIFO order is preserved through `sequence`
+ */
+export declare class MemoryWalletQueue implements IWalletQueue {
+    private readonly cryptoHelper;
+    private readonly messages;
+    private sequence;
+    constructor(cryptoHelper: ICryptoHelper);
+    /**
+     * Enqueues one outbound message.
+     */
+    enqueue(input: WalletEnqueueMessageInput): Promise<WalletQueuedMessage>;
+    /**
+     * Returns the next pending message without mutating queue state.
+     */
+    peekNextPending(): Promise<WalletQueuedMessage | undefined>;
+    /**
+     * Updates one queued message.
+     */
+    update(messageId: string, patch: Partial<WalletQueuedMessage>): Promise<WalletQueuedMessage>;
+    /**
+     * Lists all queued messages in processing order.
+     */
+    list(): Promise<WalletQueuedMessage[]>;
+}

package/dist/utils/wallet-memory-queue.js

@@ -0,0 +1,82 @@
+// Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+import { WalletMessagePriorities, WalletQueueStatuses, } from '../models/wallet.js';
+const WalletMessagePriorityOrder = {
+    [WalletMessagePriorities.Emergency]: 0,
+    [WalletMessagePriorities.High]: 1,
+    [WalletMessagePriorities.Normal]: 2,
+    [WalletMessagePriorities.Low]: 3,
+};
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function sortQueue(messages) {
+    return [...messages].sort((left, right) => {
+        const priorityDelta = WalletMessagePriorityOrder[left.priority] - WalletMessagePriorityOrder[right.priority];
+        if (priorityDelta !== 0)
+            return priorityDelta;
+        return left.sequence - right.sequence;
+    });
+}
+/**
+ * Default in-memory queue/outbox implementation for `WalletMem`.
+ *
+ * Contract:
+ * - `emergency` outranks `high`, `normal`, and `low`
+ * - within the same priority level, FIFO order is preserved through `sequence`
+ */
+export class MemoryWalletQueue {
+    cryptoHelper;
+    messages = new Map();
+    sequence = 0;
+    constructor(cryptoHelper) {
+        this.cryptoHelper = cryptoHelper;
+    }
+    /**
+     * Enqueues one outbound message.
+     */
+    async enqueue(input) {
+        this.sequence += 1;
+        const queued = {
+            id: String(input.id || this.cryptoHelper.randomUUID()).trim(),
+            createdAt: String(input.createdAt || new Date().toISOString()).trim(),
+            priority: input.priority || WalletMessagePriorities.Normal,
+            status: WalletQueueStatuses.Pending,
+            sequence: this.sequence,
+            payload: clone(input.payload),
+            ...(input.thid ? { thid: input.thid } : {}),
+            ...(input.messageType ? { messageType: input.messageType } : {}),
+        };
+        this.messages.set(queued.id, queued);
+        return clone(queued);
+    }
+    /**
+     * Returns the next pending message without mutating queue state.
+     */
+    async peekNextPending() {
+        const pending = sortQueue([...this.messages.values()].filter((message) => message.status === WalletQueueStatuses.Pending));
+        const next = pending[0];
+        return next ? clone(next) : undefined;
+    }
+    /**
+     * Updates one queued message.
+     */
+    async update(messageId, patch) {
+        const normalizedMessageId = String(messageId || '').trim();
+        const current = this.messages.get(normalizedMessageId);
+        if (!current) {
+            throw new Error(`MemoryWalletQueue message not found: ${normalizedMessageId}`);
+        }
+        const updated = {
+            ...current,
+            ...patch,
+        };
+        this.messages.set(normalizedMessageId, updated);
+        return clone(updated);
+    }
+    /**
+     * Lists all queued messages in processing order.
+     */
+    async list() {
+        return sortQueue([...this.messages.values()]).map((message) => clone(message));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "2.0.18",
+  "version": "2.1.0",
   "publishConfig": {
     "access": "public"
   },