@learncard/network-plugin 2.14.1 → 3.0.0

package/src/plugin.ts

@@ -1,3 +1,4 @@
+import { waitForInboxCredentialBatch } from './inbox-batch';
 import { getClient, getApiTokenClient } from '@learncard/network-brain-client';
 import {
     JWEValidator,
@@ -14,15 +15,20 @@ import {
     VC,
     BitstringCredentialStatusEntry,
     BitstringCredentialStatusPurpose,
+    AllocateCredentialRefreshResult,
+    ManagedCredentialRefreshReceipt,
     ManagedCredentialRefreshService,
     StoredCredentialEnvelope,
     StoredCredentialEnvelopeValidator,
     isStoredCredentialEnvelope,
+    ACT_AS_HEADER,
 } from '@learncard/types';
 import { LearnCard } from '@learncard/core';
 import { VerifyExtension } from '@learncard/vc-plugin';
 import {
+    getCredentialIssuerId,
     getCredentialStatusArray,
+    injectManagedRefreshService as injectSharedManagedRefreshService,
     isVC2Format,
     resolveStorageReadResult,
 } from '@learncard/helpers';
@@ -443,55 +449,102 @@ const issueCredentialWithNetworkStatus = async (
 };
 
 /**
- * Inline JSON-LD context fragment required to sign credentials carrying a
- * LearnCard-managed `LearnCardCredentialRefresh2026` refresh service.
+ * Injects an allocated managed refresh service into an unsigned credential so the
+ * service (and its required inline JSON-LD context) becomes part of the signed
+ * payload.
  *
- * Neither VCDM 1.1 (which defines only `ManualRefreshService2018`), VCDM 2.0, nor the
- * live OBv3 contexts define the term `LearnCardCredentialRefresh2026` (nor the LearnCard
- * `authorization` / `LearnCardDIDAuth` extension terms), so DIDKit's data-loss
- * detection refuses to sign unless issuers define these terms inline.
+ * Thin re-export of the shared {@link injectSharedManagedRefreshService} helper
+ * (LC-2198 Task 1): validates the service, rejects a second/different managed
+ * service, and prepares the inline context idempotently — replacing this plugin's
+ * former private copy that could silently overwrite an existing service and only
+ * checked context presence by key existence.
  */
-const MANAGED_REFRESH_SERVICE_CONTEXT = {
-    'LearnCardCredentialRefresh2026':
-        'https://learncard.com/refresh#LearnCardCredentialRefresh2026',
-    authorization: {
-        '@id': 'https://purl.imsglobal.org/spec/ob/v3p0#authorization',
-        '@context': {
-            LearnCardDIDAuth: 'https://docs.learncard.com/definitions#LearnCardDIDAuth',
-        },
-    },
+const injectManagedRefreshService = (
+    credential: UnsignedVC,
+    refreshService: ManagedCredentialRefreshService
+): UnsignedVC => injectSharedManagedRefreshService(credential, refreshService);
+
+const getCredentialSubjectIds = (vc: VC): string[] => {
+    const subject = (vc as Record<string, unknown>).credentialSubject;
+    const subjects = Array.isArray(subject) ? subject : subject ? [subject] : [];
+
+    return subjects.flatMap(entry => {
+        const id = (entry as Record<string, unknown> | undefined)?.id;
+
+        return typeof id === 'string' && id.length > 0 ? [id] : [];
+    });
 };
 
 /**
- * Injects an allocated managed refresh service into an unsigned credential so the
- * service becomes part of the signed payload. Appends the inline context fragment
- * unless an equivalent mapping is already present.
+ * Builds the metadata-only managed-refresh issuance receipt (LC-2198 decision 2)
+ * from the actual signed version-1 credential plus the allocation used to send it.
+ *
+ * Deliberately excludes all credential claims, subject bodies, plaintext VC
+ * content, and JWE payloads: the issuer keeps its own template/claims and retains
+ * this receipt to publish future versions (including the exact `credentialStatus`
+ * descriptor, so publishing never allocates another one).
  */
-const injectManagedRefreshService = (
-    credential: UnsignedVC,
-    refreshService: ManagedCredentialRefreshService
-): UnsignedVC => {
-    const existingContext = (credential as Record<string, unknown>)['@context'];
-    const contextList = Array.isArray(existingContext) ? existingContext : [existingContext];
-
-    const hasMapping = contextList.some(
-        entry =>
-            !!entry &&
-            typeof entry === 'object' &&
-            'LearnCardCredentialRefresh2026' in (entry as Record<string, unknown>)
-    );
+const buildManagedRefreshReceipt = (
+    vc: VC,
+    allocation: AllocateCredentialRefreshResult,
+    credentialId: string,
+    fallbackHolderDid: string,
+    fallbackIssuerDid: string
+): ManagedCredentialRefreshReceipt => {
+    const issuerDid = getCredentialIssuerId(vc) ?? fallbackIssuerDid;
+    const holderDid = getCredentialSubjectIds(vc)[0] ?? fallbackHolderDid;
+    const rawStatus = (vc as Record<string, unknown>).credentialStatus;
+
+    // Skip empty status collections (e.g. a VC2 credential whose status allocation
+    // returned no entries) — only a real descriptor round-trips for publication.
+    const hasStatus =
+        rawStatus !== undefined &&
+        rawStatus !== null &&
+        !(Array.isArray(rawStatus) && rawStatus.length === 0);
 
     return {
-        ...credential,
-        '@context': hasMapping ? contextList : [...contextList, MANAGED_REFRESH_SERVICE_CONTEXT],
-        refreshService,
-    } as UnsignedVC;
+        refreshId: allocation.refreshId,
+        refreshService: allocation.refreshService,
+        credentialId: typeof vc.id === 'string' && vc.id.length > 0 ? vc.id : credentialId,
+        issuerDid,
+        holderDid,
+        ...(hasStatus
+            ? {
+                  credentialStatus:
+                      rawStatus as ManagedCredentialRefreshReceipt['credentialStatus'],
+              }
+            : {}),
+    };
 };
 
 export * from './types';
 
 export type GuardianApprovalGetter = () => string | undefined | Promise<string | undefined>;
 
+export { ACT_AS_HEADER };
+
+// Must match the message resolveActAs throws for a missing target
+// (services/learn-card-network/brain-service/src/routes/index.ts).
+const ACT_AS_TARGET_NOT_FOUND_MESSAGE = 'Act-as target profile not found';
+
+/**
+ * True only for errors the server's act-as resolver throws when denying the delegation
+ * itself (FORBIDDEN: not a manager / policy denies; BAD_REQUEST: malformed header;
+ * NOT_FOUND: the target profile). Any other error — including a NOT_FOUND from elsewhere —
+ * is unrelated and must surface unchanged.
+ */
+const isActAsDenial = (error: unknown): boolean => {
+    const code = (error as { data?: { code?: string } } | undefined)?.data?.code;
+    if (code === 'FORBIDDEN' || code === 'BAD_REQUEST') return true;
+    if (code === 'NOT_FOUND') {
+        return (
+            (error as { message?: unknown } | undefined)?.message ===
+            ACT_AS_TARGET_NOT_FOUND_MESSAGE
+        );
+    }
+    return false;
+};
+
 /**
  * @group Plugins
  */
@@ -499,6 +552,15 @@ export type GuardianApprovalGetter = () => string | undefined | Promise<string |
 export interface LearnCardNetworkPluginOptions extends FederationConfig {
     guardianApprovalGetter?: GuardianApprovalGetter;
     extraHeaders?: Record<string, string>;
+    /**
+     * Profile ID (or managed `did:web`) to act as for every request made by this plugin
+     * instance. Sent as the `X-LearnCard-Act-As` header ({@link ACT_AS_HEADER}). The server
+     * swaps the acting profile for the duration of the request without changing token scope;
+     * it responds `403` if the caller doesn't manage the target profile, or if an API token's
+     * grant doesn't allow acting as it. Works for both API-token and seed/DID-auth clients,
+     * since seed-based users may also manage — and act as — other profiles.
+     */
+    actAs?: string;
 }
 
 export async function getLearnCardNetworkPlugin(
@@ -527,8 +589,13 @@ export async function getLearnCardNetworkPlugin(
         extraHeaders,
         trustedFederationHosts,
         allowLocalhostFederation,
+        actAs,
     } = resolvedOptions;
 
+    // Only allocate a new headers object when actAs is actually set, so behavior/identity
+    // of `extraHeaders` is unchanged for existing callers that don't use actAs.
+    const mergedExtraHeaders = actAs ? { ...extraHeaders, [ACT_AS_HEADER]: actAs } : extraHeaders;
+
     // Parse service URL to determine origin and auto-detect localhost
     const serviceUrl = new URL(url);
     const serviceIsLocalhost = isLocalhostHost(serviceUrl.hostname);
@@ -554,7 +621,7 @@ export async function getLearnCardNetworkPlugin(
 
     learnCard?.debug?.('Adding LearnCardNetwork Plugin');
     const client = apiToken
-        ? await getApiTokenClient(url, apiToken, guardianApprovalGetter, extraHeaders)
+        ? await getApiTokenClient(url, apiToken, guardianApprovalGetter, mergedExtraHeaders)
         : await getClient(
               url,
               async challenge => {
@@ -568,7 +635,7 @@ export async function getLearnCardNetworkPlugin(
                   return jwt;
               },
               guardianApprovalGetter,
-              extraHeaders
+              mergedExtraHeaders
           );
 
     let userData: LCNProfile | undefined;
@@ -857,6 +924,31 @@ export async function getLearnCardNetworkPlugin(
             getManagedProfiles: async (_learnCard, options = {}) => {
                 return client.profileManager.getManagedProfiles.query(options);
             },
+            actAs: async (_learnCard, profileId) => {
+                const actingOptions: LearnCardNetworkPluginOptions = {
+                    ...resolvedOptions,
+                    actAs: profileId,
+                };
+
+                const actingPlugin = apiToken
+                    ? await getLearnCardNetworkPlugin(_learnCard, url, apiToken, actingOptions)
+                    : await getLearnCardNetworkPlugin(_learnCard, url, actingOptions);
+
+                // The plugin's own initial getProfile is non-fatal by design, so an act-as
+                // denial would otherwise only surface later as "Please make an account first!".
+                try {
+                    await actingPlugin.methods.getLCNClient(_learnCard).profile.getProfile.query();
+                } catch (error) {
+                    if (isActAsDenial(error)) {
+                        const message =
+                            error instanceof Error ? error.message : 'Act-as request was denied.';
+                        throw new Error(message, { cause: error });
+                    }
+                    _learnCard.debug?.('LCN actAs: getProfile failed (non-fatal)', error);
+                }
+
+                return _learnCard.addPlugin(actingPlugin);
+            },
             claimPendingGuardianLinks: async () => {
                 await ensureUser();
                 return client.inbox.claimPendingGuardianLinks.mutate({});
@@ -1703,7 +1795,7 @@ export async function getLearnCardNetworkPlugin(
 
                 const enableRefresh = typeof options === 'object' && options.enableRefresh === true;
 
-                let managedRefreshId: string | undefined;
+                let refreshAllocation: AllocateCredentialRefreshResult | undefined;
 
                 if (enableRefresh) {
                     // Generate a stable UUID credential ID when the template has none;
@@ -1711,15 +1803,16 @@ export async function getLearnCardNetworkPlugin(
                     if (!boost.id) boost.id = `urn:uuid:${crypto.randomUUID()}`;
 
                     // Allocate BEFORE signing: the refresh service must be part of the
-                    // signed payload, so it is injected before proof creation.
-                    const allocation =
+                    // signed payload, so it is injected before proof creation. The
+                    // allocation descriptor is retained through signing so the receipt
+                    // can be returned alongside the issued credential URI.
+                    refreshAllocation =
                         await client.credentialRefresh.allocateCredentialRefresh.mutate({
                             holder: { profileId, did: targetProfile.did },
                             credentialId: boost.id,
                         });
 
-                    managedRefreshId = allocation.refreshId;
-                    boost = injectManagedRefreshService(boost, allocation.refreshService);
+                    boost = injectManagedRefreshService(boost, refreshAllocation.refreshService);
                 }
 
                 const statusPurposes =
@@ -1731,20 +1824,37 @@ export async function getLearnCardNetworkPlugin(
                     statusPurposes
                 );
 
-                if (managedRefreshId) {
+                if (refreshAllocation) {
                     // Dedicated managed send: brain-service verifies the proof and
                     // persists ONLY a holder-encrypted JWE. Legacy credential storage
-                    // (issuer/LCN-readable JWE or plaintext) is intentionally bypassed.
+                    // (issuer/LCN-readable JWE or plaintext) is intentionally bypassed —
+                    // managed encryption is mandatory even when `encrypt: false`.
                     // The boost URI is forwarded so the credential stays linked
                     // INSTANCE_OF the boost for canonical recipient management.
-                    return client.credentialRefresh.sendRefreshableCredential.mutate({
-                        refreshId: managedRefreshId,
-                        credential: vc,
-                        boostUri,
-                        ...(typeof options === 'object' && options.skipNotification
-                            ? { skipNotification: true }
-                            : {}),
-                    });
+                    const credentialUri =
+                        await client.credentialRefresh.sendRefreshableCredential.mutate({
+                            refreshId: refreshAllocation.refreshId,
+                            credential: vc,
+                            boostUri,
+                            ...(typeof options === 'object' && options.skipNotification
+                                ? { skipNotification: true }
+                                : {}),
+                        });
+
+                    // Refresh-enabled callers get the issuance receipt needed to publish
+                    // future versions, populated from the actual signed version 1
+                    // (LC-2198 decision 4). Non-opt-in callers still receive a plain URI
+                    // string.
+                    return {
+                        credentialUri,
+                        refresh: buildManagedRefreshReceipt(
+                            vc,
+                            refreshAllocation,
+                            boost.id ?? '',
+                            targetProfile.did,
+                            _learnCard.id.did()
+                        ),
+                    };
                 }
 
                 // options is allowed to be a boolean to maintain backwards compatibility
@@ -1828,6 +1938,145 @@ export async function getLearnCardNetworkPlugin(
             send: async (_learnCard, input) => {
                 await ensureUser();
 
+                if (input.type === 'boost' && input.refresh === true) {
+                    // LC-2198: dedicated managed-refresh branch — evaluated BEFORE the
+                    // ordinary local-signing / remote-DID / federation shortcuts so a
+                    // refresh request can never fall back to a non-refresh delivery.
+                    // Inbox credentials stay unsigned until a verified claimant binds their DID.
+                    const isEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(input.recipient);
+                    const isPhone = /^\+?[\d\s-]{10,}$/.test(input.recipient.replace(/[\s-]/g, ''));
+                    if (isEmail || isPhone) return client.boost.send.mutate(input);
+
+                    const canIssueLocally = 'issueCredential' in _learnCard.invoke;
+
+                    if (
+                        canIssueLocally &&
+                        !input.signedCredential &&
+                        (input.templateUri || input.template)
+                    ) {
+                        // Local signing. Load the template first (read-only) so a template-
+                        // supplied credential ID is honored, then let the server run every
+                        // managed-send guard, create/reuse the boost and allocate the refresh
+                        // in ONE step. With an idempotencyKey that step also makes the whole
+                        // call retryable; `completed` means this key already delivered.
+                        let boost: UnsignedVC;
+
+                        if (input.templateUri) {
+                            const result = await getBoostTemplateForIssuance(
+                                _learnCard,
+                                input.templateUri
+                            );
+                            const data = await UnsignedVCValidator.spa(result);
+
+                            if (!data.success)
+                                throw new Error('Did not get a valid boost from URI');
+
+                            boost = data.data;
+                        } else {
+                            // Clone before preparation so template rendering never
+                            // mutates the caller's claims.
+                            boost = JSON.parse(
+                                JSON.stringify(input.template!.credential)
+                            ) as UnsignedVC;
+                        }
+
+                        const prepared = await client.boost.prepareRefreshableSend.mutate({
+                            recipient: input.recipient,
+                            ...(input.templateUri
+                                ? { templateUri: input.templateUri }
+                                : { template: input.template! }),
+                            ...(input.contractUri ? { contractUri: input.contractUri } : {}),
+                            ...(input.templateData ? { templateData: input.templateData } : {}),
+                            ...(input.integrationId ? { integrationId: input.integrationId } : {}),
+                            ...(boost.id ? { credentialId: boost.id } : {}),
+                            ...(input.idempotencyKey
+                                ? { idempotencyKey: input.idempotencyKey }
+                                : {}),
+                        });
+
+                        if (prepared.completed) return prepared.completed;
+
+                        const boostString = JSON.stringify(boost);
+                        const allowAutoAppendEvidence = !hasDynamicEvidenceTemplate(boostString);
+
+                        if (input.templateData && Object.keys(input.templateData).length > 0) {
+                            try {
+                                const rendered = renderTemplateJson(
+                                    boostString,
+                                    input.templateData
+                                );
+                                boost = JSON.parse(rendered);
+                                boost = appendTemplateEvidence(
+                                    boost,
+                                    input.templateData,
+                                    allowAutoAppendEvidence
+                                );
+                            } catch (error) {
+                                throw new Error(
+                                    `Failed to apply template data: ${
+                                        error instanceof Error ? error.message : 'Unknown error'
+                                    }`,
+                                    { cause: error }
+                                );
+                            }
+                        }
+
+                        if (isVC2Format(boost)) {
+                            boost.validFrom = new Date().toISOString();
+                        } else {
+                            boost.issuanceDate = new Date().toISOString();
+                        }
+
+                        boost.issuer = _learnCard.id.did();
+
+                        if (Array.isArray(boost.credentialSubject)) {
+                            boost.credentialSubject = boost.credentialSubject.map(subject => ({
+                                ...subject,
+                                id: prepared.holderDid,
+                            }));
+                        } else {
+                            boost.credentialSubject = {
+                                ...boost.credentialSubject,
+                                id: prepared.holderDid,
+                            };
+                        }
+
+                        // The refresh aggregate is permanently bound to this ID.
+                        boost.id = prepared.credentialId;
+
+                        if (boost.type?.includes('BoostCredential'))
+                            boost.boostId = prepared.boostUri;
+
+                        boost = injectManagedRefreshService(boost, prepared.refreshService);
+
+                        // Signing goes through the vc-plugin boundary, which prepares the
+                        // managed inline JSON-LD context — the service and its terms are
+                        // signed in one proof, never mutated afterwards.
+                        const signedCredential = await issueCredentialWithNetworkStatus(
+                            _learnCard,
+                            client,
+                            boost
+                        );
+
+                        // Validated handoff: the server re-derives the refresh ID from the
+                        // signed service, re-validates ownership/holder/proof, records the
+                        // idempotency intent, and returns the canonical receipt.
+                        return client.boost.send.mutate({
+                            ...input,
+                            template: undefined,
+                            templateUri: prepared.boostUri,
+                            signedCredential,
+                            refresh: true,
+                        });
+                    }
+
+                    // No local signing capability (or caller-supplied signedCredential,
+                    // which is forwarded untouched — its proof is never mutated):
+                    // delegate the unchanged refresh request to the server signing
+                    // authority path.
+                    return client.boost.send.mutate(input);
+                }
+
                 if (input.type === 'boost') {
                     const recipient = input.recipient;
                     const isDid = recipient.startsWith('did:');
@@ -2393,6 +2642,37 @@ export async function getLearnCardNetworkPlugin(
 
                 return client.inbox.issue.mutate(issueInboxCredential);
             },
+            sendCredentialsViaInbox: async (_learnCard, batch) => {
+                await ensureUser();
+                return client.inbox.issueBatch.mutate(batch);
+            },
+            sendCredentialBatchViaInbox: async (_learnCard, batch) => {
+                await ensureUser();
+                return client.inbox.issueBatch.mutate(batch);
+            },
+            waitForInboxCredentialBatch: async (_learnCard, batchId, options) => {
+                await ensureUser();
+                return waitForInboxCredentialBatch(
+                    signal => client.inbox.getBatch.query({ batchId }, { signal }),
+                    options
+                );
+            },
+            sendCredentialsViaInboxAndWait: async (_learnCard, batch, options) => {
+                await ensureUser();
+                if (options?.signal?.aborted) throw options.signal.reason;
+                const receipt = await client.inbox.issueBatch.mutate(batch, {
+                    signal: options?.signal,
+                });
+                await options?.onSubmitted?.(receipt);
+                return waitForInboxCredentialBatch(
+                    signal => client.inbox.getBatch.query({ batchId: receipt.batchId }, { signal }),
+                    options
+                );
+            },
+            getInboxCredentialBatch: async (_learnCard, batchId) => {
+                await ensureUser();
+                return client.inbox.getBatch.query({ batchId });
+            },
             getMySentInboxCredentials: async (_learnCard, options) => {
                 await ensureUser();