@learncard/network-brain-service 3.18.0 → 3.19.1

package/src/inbox-queue-local.ts

@@ -0,0 +1,28 @@
+import {
+    consumeInboxQueueOnce,
+    consumeInboxDeadLettersOnce,
+    dispatchInboxJobs,
+} from './helpers/inbox-queue.helpers';
+
+let running = true;
+process.on('SIGINT', () => {
+    running = false;
+});
+process.on('SIGTERM', () => {
+    running = false;
+});
+
+/** Run separately from the HTTP process; restarting either process leaves durable jobs intact. */
+const run = async (): Promise<void> => {
+    while (running) {
+        try {
+            await dispatchInboxJobs();
+            await consumeInboxQueueOnce(10);
+            await consumeInboxDeadLettersOnce();
+        } catch {
+            console.error('Inbox queue iteration failed; durable jobs will be retried.');
+            await new Promise(resolve => setTimeout(resolve, 1000));
+        }
+    }
+};
+void run();

package/src/models/AuthGrant.ts

@@ -21,6 +21,7 @@ export const AuthGrant = ModelFactory<FlatAuthGrantType, AuthGrantRelationships>
             challenge: { type: 'string', required: true, uniqueItems: true },
             status: { type: 'string', required: true },
             scope: { type: 'string', required: true },
+            actAs: { type: 'string', required: false },
             createdAt: { type: 'string', required: true },
             expiresAt: { type: 'string', required: false },
         },

package/src/models/CredentialActivity.ts

@@ -7,11 +7,7 @@ import { Boost, BoostInstance } from './Boost';
 import { AppStoreListing, AppStoreListingInstance } from './AppStoreListing';
 
 export type CredentialActivityEventType =
-    | 'CREATED'
-    | 'DELIVERED'
-    | 'CLAIMED'
-    | 'EXPIRED'
-    | 'FAILED';
+    'CREATED' | 'DELIVERED' | 'CLAIMED' | 'EXPIRED' | 'FAILED';
 
 export type CredentialActivityRecipientType = 'profile' | 'email' | 'phone';
 
@@ -32,6 +28,7 @@ export type CredentialActivityType = {
     eventType: CredentialActivityEventType;
     timestamp: string;
     actorProfileId?: string;
+    onBehalfOf?: string;
     recipientType: CredentialActivityRecipientType;
     recipientIdentifier: string;
     boostUri?: string;
@@ -70,6 +67,7 @@ export const CredentialActivity = ModelFactory<
             },
             timestamp: { type: 'string', required: true },
             actorProfileId: { type: 'string', required: false },
+            onBehalfOf: { type: 'string', required: false },
             recipientType: {
                 type: 'string',
                 required: true,

package/src/models/CredentialRefresh.ts

@@ -36,16 +36,18 @@ export const CredentialRefresh = ModelFactory<
     {
         label: 'CredentialRefresh',
         schema: {
+            inboxCredentialId: { type: 'string', required: false },
+            inboxCredentialStatus: { type: 'string', required: false },
             refreshId: { type: 'string', required: true },
             issuerProfileId: { type: 'string', required: true },
             issuerDid: { type: 'string', required: true },
             holderProfileId: { type: 'string', required: false },
-            holderDid: { type: 'string', required: true },
+            holderDid: { type: 'string', required: false },
             credentialId: { type: 'string', required: true },
             state: {
                 type: 'string',
                 required: true,
-                enum: ['awaiting_claim', 'active', 'revoked'],
+                enum: ['pending_holder', 'awaiting_claim', 'active', 'revoked'],
             },
             currentVersion: { type: 'number', required: true },
             etag: { type: 'string', required: false },

package/src/models/InboxCredential.ts

@@ -6,6 +6,7 @@ import { Profile, ProfileInstance } from './Profile';
 import ContactMethod, { ContactMethodInstance } from './ContactMethod';
 
 export type InboxCredentialType = {
+    refreshId?: string;
     id: string;
     credential?: string; // Versioned JWE; removed immediately after successful finalization
     isSigned: boolean;
@@ -86,6 +87,7 @@ export const InboxCredential = ModelFactory<InboxCredentialType, InboxCredential
     {
         label: 'InboxCredential',
         schema: {
+            refreshId: { type: 'string', required: false },
             id: { type: 'string', required: true, uniqueItems: true },
             credential: { type: 'string', required: false },
             isSigned: { type: 'boolean', required: true },

package/src/models/Presentation.ts

@@ -9,8 +9,8 @@ export type PresentationRelationships = {
     presentationReceived: ModelRelatedNodesI<
         { createOne: (typeof Profile)['createOne'] },
         ProfileInstance,
-        { from: string; date: string },
-        { from: string; date: string }
+        { from: string; date: string; metadata?: Record<string, unknown> },
+        { from: string; date: string; metadata?: Record<string, unknown> }
     >;
 };
 

package/src/models/Profile.ts

@@ -75,8 +75,8 @@ export type ProfileRelationships = {
     presentationSent: ModelRelatedNodesI<
         typeof Presentation,
         PresentationInstance,
-        { to: string; date: string },
-        { to: string; date: string }
+        { to: string; date: string; metadata?: Record<string, unknown> },
+        { to: string; date: string; metadata?: Record<string, unknown> }
     >;
     usesSigningAuthority: ModelRelatedNodesI<
         typeof SigningAuthority,
@@ -238,6 +238,7 @@ export const Profile: any = ModelFactory<FlatProfileType, ProfileRelationships>(
                 properties: {
                     to: { property: 'to', schema: { type: 'string', required: true } },
                     date: { property: 'date', schema: { type: 'string', required: true } },
+                    metadata: { property: 'metadata', schema: { type: 'object', required: false } },
                 },
             },
             usesSigningAuthority: {

package/src/models/ShareLink.ts

@@ -0,0 +1,130 @@
+import { ModelFactory, NeogmaInstance } from 'neogma';
+
+import { neogma } from '@instance';
+
+/** Lifecycle status of a share. Only `active` is ever served to a recipient. */
+export type ShareLinkStatus = 'pending' | 'active' | 'stopped';
+
+/**
+ * Whether the visible content pointer for a share is committed.
+ *
+ * `staging` means a reservation exists but the object is not visible yet;
+ * `content_missing` means Brain believes content should be visible but LearnCloud
+ * does not have it, so the share fails closed and is never served.
+ */
+export type ShareContentState = 'staging' | 'finalized' | 'content_missing';
+
+/**
+ * Persisted ShareLink metadata (LC-2187).
+ *
+ * This node is the only Brain-side source of truth for the *visible* content
+ * pointer. It stores an opaque immutable `activeObjectRef` plus content/recovery
+ * hashes and byte counts — never ciphertext, a raw private source URI or a key.
+ * The concrete encrypted envelope and owner recovery JWE live together in the
+ * dedicated LearnCloud collection keyed by the immutable object reference.
+ *
+ * `version` is the committed record revision used for optimistic concurrency; a
+ * reservation (`staging`) does not change it. `contentVersion` is the visible
+ * content revision and changes only when a replacement is finalized.
+ */
+export type ShareLinkRecord = {
+    id: string;
+    namespace: string;
+    ownerProfileId: string;
+    version: number;
+    contentVersion: number;
+    /**
+     * Monotonic fence. Bumped on every reservation and on revoke; a worker may
+     * only finalize the reservation whose generation still equals this value.
+     */
+    generation: number;
+    status: ShareLinkStatus;
+    contentState: ShareContentState;
+    activeObjectRef: string | null;
+    activeObjectOperationId: string | null;
+    activeContentHash: string | null;
+    activeContentBytes: number | null;
+    activeRecoveryHash: string | null;
+    /** Operation binding: the operation id that produced the visible revision. */
+    lastOperationId: string | null;
+    /** Operation binding: the create request that first bound this share id. */
+    createdByClientRequestId: string | null;
+    title: string;
+    note: string | null;
+    selectedCount: number;
+    expiresAt: string | null;
+    stoppedAt: string | null;
+    viewCount: number;
+    lastViewedAt: string | null;
+    /** Argon2id PHC string. Plaintext passcodes are never persisted. */
+    passcodeHash?: string | null;
+    notifyOnView?: boolean;
+    minorPolicyIsMinor: boolean | null;
+    minorPolicyResolved: boolean;
+    minorPolicyDefaultExpiryDays: number;
+    minorPolicyViewCountingEnabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+};
+
+/** Neo4j omits null properties; the repository maps missing values back to null. */
+type ShareLinkProperties = { lockTick?: number } & {
+    [Key in keyof ShareLinkRecord]:
+        | Exclude<ShareLinkRecord[Key], null>
+        | (null extends ShareLinkRecord[Key] ? undefined : never);
+};
+export type ShareLinkInstance = NeogmaInstance<ShareLinkProperties, Record<string, never>>;
+
+/**
+ * `:ShareLink` model registration. The repository writes this label with raw
+ * parameterized Cypher so it can hold the share write lock across read + write
+ * within one transaction; the model exists for schema/typed instance support and
+ * constraint registration.
+ */
+export const ShareLink = ModelFactory<ShareLinkProperties, Record<string, never>>(
+    {
+        label: 'ShareLink',
+        schema: {
+            id: { type: 'string', required: true },
+            namespace: { type: 'string', required: true },
+            ownerProfileId: { type: 'string', required: true },
+            version: { type: 'number', required: true },
+            contentVersion: { type: 'number', required: true },
+            generation: { type: 'number', required: true },
+            status: { type: 'string', required: true, enum: ['pending', 'active', 'stopped'] },
+            contentState: {
+                type: 'string',
+                required: true,
+                enum: ['staging', 'finalized', 'content_missing'],
+            },
+            activeObjectRef: { type: 'string', required: false },
+            activeObjectOperationId: { type: 'string', required: false },
+            activeContentHash: { type: 'string', required: false },
+            activeContentBytes: { type: 'number', required: false },
+            activeRecoveryHash: { type: 'string', required: false },
+            lastOperationId: { type: 'string', required: false },
+            createdByClientRequestId: { type: 'string', required: false },
+            title: { type: 'string', required: true },
+            note: { type: 'string', required: false },
+            selectedCount: { type: 'number', required: true },
+            expiresAt: { type: 'string', required: false },
+            stoppedAt: { type: 'string', required: false },
+            viewCount: { type: 'number', required: true },
+            lastViewedAt: { type: 'string', required: false },
+            passcodeHash: { type: 'string', required: false },
+            // LC-2187 records created before opt-in alerts may omit this field.
+            notifyOnView: { type: 'boolean', required: false },
+            minorPolicyIsMinor: { type: 'boolean', required: false },
+            minorPolicyResolved: { type: 'boolean', required: true },
+            minorPolicyDefaultExpiryDays: { type: 'number', required: true },
+            minorPolicyViewCountingEnabled: { type: 'boolean', required: true },
+            createdAt: { type: 'string', required: true },
+            updatedAt: { type: 'string', required: true },
+            lockTick: { type: 'number', required: false },
+        },
+        primaryKeyField: 'id',
+    },
+    neogma
+);
+
+export default ShareLink;

package/src/models/ShareViewReceipt.ts

@@ -0,0 +1,69 @@
+import { ModelFactory, NeogmaInstance } from 'neogma';
+
+import { neogma } from '@instance';
+
+/**
+ * Persisted, short-lived view receipt (LC-2187 ADR-10).
+ *
+ * Only the hash of the opaque CSPRNG token is stored — never the token, a viewer
+ * identity, an IP, a fingerprint, a credential, a key or any request body. The
+ * node is bound to one immutable committed tuple
+ * `(namespace, ownerProfileId, shareId, contentVersion, objectRef, operationId)`
+ * so a receipt for a superseded revision can never count toward the current one.
+ *
+ * `consumedAt` is the single-use marker; `lockTick` exists only so a transaction
+ * can take a write lock on the receipt AFTER it holds the share write lock.
+ * `expiresAt` bounds retention and is indexed for one-shot pruning.
+ */
+export type ShareViewReceiptRecord = {
+    receiptHash: string;
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectRef: string;
+    operationId: string;
+    createdAt: string;
+    expiresAt: string;
+    consumedAt: string | null;
+};
+
+type ShareViewReceiptProperties = { lockTick?: number } & {
+    [Key in keyof ShareViewReceiptRecord]:
+        | Exclude<ShareViewReceiptRecord[Key], null>
+        | (null extends ShareViewReceiptRecord[Key] ? undefined : never);
+};
+
+export type ShareViewReceiptInstance = NeogmaInstance<
+    ShareViewReceiptProperties,
+    Record<string, never>
+>;
+
+/**
+ * `:ShareViewReceipt` model registration. The repository writes this label with
+ * raw parameterized Cypher so consume + increment happen in one transaction with
+ * explicit share-then-receipt lock ordering; the model exists for schema and
+ * constraint registration.
+ */
+export const ShareViewReceipt = ModelFactory<ShareViewReceiptProperties, Record<string, never>>(
+    {
+        label: 'ShareViewReceipt',
+        schema: {
+            receiptHash: { type: 'string', required: true },
+            namespace: { type: 'string', required: true },
+            ownerProfileId: { type: 'string', required: true },
+            shareId: { type: 'string', required: true },
+            contentVersion: { type: 'number', required: true },
+            objectRef: { type: 'string', required: true },
+            operationId: { type: 'string', required: true },
+            createdAt: { type: 'string', required: true },
+            expiresAt: { type: 'string', required: true },
+            consumedAt: { type: 'string', required: false },
+            lockTick: { type: 'number', required: false },
+        },
+        primaryKeyField: 'receiptHash',
+    },
+    neogma
+);
+
+export default ShareViewReceipt;

package/src/models/credential-refresh-constraints.test.ts

@@ -38,11 +38,16 @@ describe('credential refresh constraint readiness', () => {
         releaseFirstQuery();
         await Promise.all([first, second]);
 
-        expect(mocks.run).toHaveBeenCalledTimes(3);
+        expect(mocks.run).toHaveBeenCalledTimes(8);
         expect(mocks.run.mock.calls.map(([query]) => query)).toEqual([
+            'CREATE CONSTRAINT inbox_refresh_issue_key_unique IF NOT EXISTS FOR (i:InboxCredential) REQUIRE (i.refreshIssueKey) IS UNIQUE',
+            'CREATE CONSTRAINT inbox_refresh_publication_key_unique IF NOT EXISTS FOR (p:InboxRefreshPublication) REQUIRE (p.refreshIdempotencyKey) IS UNIQUE',
+            'CREATE CONSTRAINT inbox_refresh_version_key_unique IF NOT EXISTS FOR (p:InboxRefreshPublication) REQUIRE (p.refreshVersionKey) IS UNIQUE',
             'CREATE CONSTRAINT credential_refresh_id_unique IF NOT EXISTS FOR (r:CredentialRefresh) REQUIRE (r.refreshId) IS UNIQUE',
             'CREATE CONSTRAINT credential_refresh_version_key_unique IF NOT EXISTS FOR (c:Credential) REQUIRE (c.refreshVersionKey) IS UNIQUE',
             'CREATE CONSTRAINT credential_refresh_idempotency_key_unique IF NOT EXISTS FOR (c:Credential) REQUIRE (c.refreshIdempotencyKey) IS UNIQUE',
+            'CREATE CONSTRAINT credential_refresh_email_delivery_key_unique IF NOT EXISTS FOR (d:CredentialRefreshEmailDelivery) REQUIRE (d.deliveryKey) IS UNIQUE',
+            'CREATE CONSTRAINT refresh_send_intent_key_unique IF NOT EXISTS FOR (i:RefreshSendIntent) REQUIRE (i.intentKey) IS UNIQUE',
         ]);
     });
 
@@ -57,7 +62,7 @@ describe('credential refresh constraint readiness', () => {
             await import('./credential-refresh-constraints');
 
         await expect(ensureCredentialRefreshConstraints()).resolves.toBeUndefined();
-        expect(mocks.run).toHaveBeenCalledTimes(3);
+        expect(mocks.run).toHaveBeenCalledTimes(8);
     });
 
     it('clears failed readiness so a later request can retry', async () => {
@@ -70,6 +75,6 @@ describe('credential refresh constraint readiness', () => {
         await expect(ensureCredentialRefreshConstraints()).rejects.toBe(setupFailure);
         await expect(ensureCredentialRefreshConstraints()).resolves.toBeUndefined();
 
-        expect(mocks.run).toHaveBeenCalledTimes(4);
+        expect(mocks.run).toHaveBeenCalledTimes(9);
     });
 });

package/src/models/credential-refresh-constraints.ts

@@ -1,9 +1,14 @@
 import { neogma } from '@instance';
 
 const CREDENTIAL_REFRESH_CONSTRAINT_QUERIES = [
+    'CREATE CONSTRAINT inbox_refresh_issue_key_unique IF NOT EXISTS FOR (i:InboxCredential) REQUIRE (i.refreshIssueKey) IS UNIQUE',
+    'CREATE CONSTRAINT inbox_refresh_publication_key_unique IF NOT EXISTS FOR (p:InboxRefreshPublication) REQUIRE (p.refreshIdempotencyKey) IS UNIQUE',
+    'CREATE CONSTRAINT inbox_refresh_version_key_unique IF NOT EXISTS FOR (p:InboxRefreshPublication) REQUIRE (p.refreshVersionKey) IS UNIQUE',
     'CREATE CONSTRAINT credential_refresh_id_unique IF NOT EXISTS FOR (r:CredentialRefresh) REQUIRE (r.refreshId) IS UNIQUE',
     'CREATE CONSTRAINT credential_refresh_version_key_unique IF NOT EXISTS FOR (c:Credential) REQUIRE (c.refreshVersionKey) IS UNIQUE',
     'CREATE CONSTRAINT credential_refresh_idempotency_key_unique IF NOT EXISTS FOR (c:Credential) REQUIRE (c.refreshIdempotencyKey) IS UNIQUE',
+    'CREATE CONSTRAINT credential_refresh_email_delivery_key_unique IF NOT EXISTS FOR (d:CredentialRefreshEmailDelivery) REQUIRE (d.deliveryKey) IS UNIQUE',
+    'CREATE CONSTRAINT refresh_send_intent_key_unique IF NOT EXISTS FOR (i:RefreshSendIntent) REQUIRE (i.intentKey) IS UNIQUE',
 ];
 
 type Neo4jSchemaError = {

package/src/models/index.ts

@@ -69,6 +69,7 @@ Presentation.addRelationships({
         properties: {
             from: { property: 'from', schema: { type: 'string', required: true } },
             date: { property: 'date', schema: { type: 'string', required: true } },
+            metadata: { property: 'metadata', schema: { type: 'object', required: false } },
         },
     },
 });
@@ -256,4 +257,5 @@ export * from './Integration';
 export * from './AppStoreListing';
 export * from './CredentialActivity';
 export * from './CredentialRefresh';
+export * from './ShareLink';
 export * from './StatusList';

package/src/models/share-link-constraints.ts

@@ -0,0 +1,93 @@
+import { neogma } from '@instance';
+
+/**
+ * Uniqueness rules required for the LC-2187 share lifecycle.
+ *
+ * A uniqueness constraint alone does not serialize two transactions consuming one
+ * reservation; the repository additionally holds a `:ShareLink` write lock before
+ * reading status/version/reservation state. These rules are the hard backstop that
+ * makes the resulting race fail closed instead of forking state.
+ */
+const SHARE_LINK_CONSTRAINT_QUERIES = [
+    // A share id is globally unique across namespaces.
+    'CREATE CONSTRAINT share_link_id_unique IF NOT EXISTS FOR (s:ShareLink) REQUIRE (s.id) IS UNIQUE',
+    // One idempotency record per (namespace, owner, operation kind, client request).
+    'CREATE CONSTRAINT share_link_operation_key_unique IF NOT EXISTS FOR (o:ShareLinkOperation) REQUIRE (o.namespace, o.ownerProfileId, o.opKind, o.clientRequestId) IS UNIQUE',
+    // At most one in-flight reservation per share.
+    'CREATE CONSTRAINT share_link_reservation_share_unique IF NOT EXISTS FOR (r:ShareLinkReservation) REQUIRE (r.shareId) IS UNIQUE',
+    // Cleanup is bound to exactly one immutable object reference.
+    'CREATE CONSTRAINT share_content_cleanup_object_unique IF NOT EXISTS FOR (c:ShareContentCleanupJob) REQUIRE (c.objectRef) IS UNIQUE',
+    // One persisted receipt node per opaque token hash (the token itself is never stored).
+    'CREATE CONSTRAINT share_view_receipt_hash_unique IF NOT EXISTS FOR (v:ShareViewReceipt) REQUIRE (v.receiptHash) IS UNIQUE',
+];
+
+/**
+ * Non-unique indexes that keep the lifecycle queries bounded. Index creation is
+ * idempotent and shares the same readiness gate as the constraints.
+ */
+const SHARE_LINK_INDEX_QUERIES = [
+    'CREATE INDEX share_link_ns_owner_idx IF NOT EXISTS FOR (s:ShareLink) ON (s.namespace, s.ownerProfileId)',
+    // Bounded owner-list keyset pagination: filters on the leading
+    // (namespace, ownerProfileId) prefix and orders by the immutable
+    // (createdAt, id) key without a full scan/sort.
+    'CREATE INDEX share_link_ns_owner_created_idx IF NOT EXISTS FOR (s:ShareLink) ON (s.namespace, s.ownerProfileId, s.createdAt, s.id)',
+    'CREATE INDEX share_link_status_idx IF NOT EXISTS FOR (s:ShareLink) ON (s.status)',
+    'CREATE INDEX share_link_operation_operation_id_idx IF NOT EXISTS FOR (o:ShareLinkOperation) ON (o.operationId)',
+    'CREATE INDEX share_link_operation_share_id_idx IF NOT EXISTS FOR (o:ShareLinkOperation) ON (o.shareId)',
+    'CREATE INDEX share_link_reservation_lease_idx IF NOT EXISTS FOR (r:ShareLinkReservation) ON (r.leaseExpiresAt)',
+    // Bounded recovery discovery enumerates expired reservations for one namespace.
+    'CREATE INDEX share_link_reservation_ns_lease_idx IF NOT EXISTS FOR (r:ShareLinkReservation) ON (r.namespace, r.leaseExpiresAt)',
+    'CREATE INDEX share_content_cleanup_due_idx IF NOT EXISTS FOR (c:ShareContentCleanupJob) ON (c.status, c.nextAttemptAt)',
+    // One-shot receipt pruning is bounded by expiry/consumed state.
+    'CREATE INDEX share_view_receipt_expiry_idx IF NOT EXISTS FOR (v:ShareViewReceipt) ON (v.expiresAt)',
+    'CREATE INDEX share_view_receipt_share_idx IF NOT EXISTS FOR (v:ShareViewReceipt) ON (v.namespace, v.shareId)',
+];
+
+type Neo4jSchemaError = {
+    code?: string;
+};
+
+const isEquivalentSchemaRuleRace = (error: unknown): boolean =>
+    (error as Neo4jSchemaError | undefined)?.code ===
+    'Neo.ClientError.Schema.EquivalentSchemaRuleAlreadyExists';
+
+const createShareLinkSchema = async (): Promise<void> => {
+    for (const query of [...SHARE_LINK_CONSTRAINT_QUERIES, ...SHARE_LINK_INDEX_QUERIES]) {
+        try {
+            await neogma.queryRunner.run(query);
+        } catch (error) {
+            // Concurrent service starts can both observe a missing rule before one
+            // wins creation. The losing CREATE is equivalent to the desired ready state.
+            if (!isEquivalentSchemaRuleRace(error)) throw error;
+        }
+    }
+};
+
+let constraintReadiness: Promise<void> | undefined;
+
+/**
+ * Ensures the uniqueness rules and indexes required for the share lifecycle.
+ *
+ * Every public repository method awaits this before its transaction, so a caller
+ * can never observe the "constraints not initialized" window. Concurrent callers
+ * share one attempt; a failed attempt is cleared so a later request can retry
+ * instead of leaving the repository permanently unavailable.
+ */
+export const ensureShareLinkConstraints = (): Promise<void> => {
+    if (!constraintReadiness) {
+        const pendingReadiness = createShareLinkSchema();
+        constraintReadiness = pendingReadiness;
+
+        void pendingReadiness.catch(() => {
+            if (constraintReadiness === pendingReadiness) constraintReadiness = undefined;
+        });
+    }
+
+    return constraintReadiness;
+};
+
+/** Exposed for focused tests that assert the exact schema statements. */
+export const SHARE_LINK_SCHEMA_QUERIES = [
+    ...SHARE_LINK_CONSTRAINT_QUERIES,
+    ...SHARE_LINK_INDEX_QUERIES,
+] as const;

package/src/openapi.ts

@@ -25,6 +25,14 @@ export const openApiDocument = generateOpenApiDocument(appRouter, {
     ],
 });
 
+// Keep this path/status aligned with inboxBatchResponseMeta in helpers/inbox-batch-http.helpers.ts.
+// The adapter's responseMeta returns 202 for durable batch acceptance.
+const batchResponses = openApiDocument.paths?.['/inbox/issue-batch']?.post?.responses;
+if (batchResponses?.['200']) {
+    batchResponses['202'] = batchResponses['200'];
+    delete batchResponses['200'];
+}
+
 // trpc-to-openapi requires a top-level ZodObject and cannot render the validator's
 // cross-field refinement. Preserve the runtime-safe object parser while documenting
 // the two mutually exclusive publication shapes for generated OpenAPI clients.

package/src/public-share-link-http.ts

@@ -0,0 +1,49 @@
+import type { FastifyInstance } from 'fastify';
+
+/**
+ * LC-2187 public share-link HTTP adapter seam.
+ *
+ * The Fastify OpenAPI adapter has no `responseMeta` hook, so the no-store
+ * contract for the anonymous public share-link routes is applied at the adapter
+ * boundary itself. This module is deliberately free of the server bootstrap
+ * (which listens on import) so a real Fastify instance can be exercised in
+ * tests without starting the application.
+ */
+
+/**
+ * Prefixes that identify a mounted public share-link OpenAPI request.
+ *
+ * The trpc-to-openapi Fastify adapter rewrites `request.raw.url` by stripping
+ * its `/api` base path before the handler runs, so the `onSend` hook sees
+ * `/public/share-links/...` even though the client requested
+ * `/api/public/share-links/...`. Both forms are matched (with a path-boundary
+ * check) so a sibling route such as `/public/share-links-other` is not treated
+ * as public.
+ */
+const PUBLIC_SHARE_LINK_PREFIXES = ['/api/public/share-links', '/public/share-links'] as const;
+
+/** True for the mounted public share-link OpenAPI route prefix only. */
+export const isPublicShareLinkOpenApiRequestUrl = (url: string | undefined): boolean => {
+    if (!url) return false;
+
+    const path = url.split('?')[0] ?? '';
+
+    return PUBLIC_SHARE_LINK_PREFIXES.some(
+        prefix => path === prefix || path.startsWith(`${prefix}/`)
+    );
+};
+
+/**
+ * Installs the adapter-boundary `Cache-Control: private, no-store` on every
+ * public share-link OpenAPI response, independent of any upstream cache layer.
+ * It is safe to register on any Fastify instance (tRPC-only test apps included).
+ */
+export const registerPublicShareLinkNoStore = (app: FastifyInstance): void => {
+    app.addHook('onSend', async (request, reply, payload) => {
+        if (isPublicShareLinkOpenApiRequestUrl(request.raw.url)) {
+            reply.header('Cache-Control', 'private, no-store');
+        }
+
+        return payload;
+    });
+};