@learncard/learn-cloud-service 2.5.34 → 2.5.35

package/src/accesslayer/share-content/index.ts

@@ -0,0 +1,70 @@
+import type { Collection, Db } from 'mongodb';
+
+import {
+    SHARE_CONTENT_COLLECTION,
+    type MongoShareContentDocument,
+    type ShareContentObjectBinding,
+    type ShareContentPutInput,
+} from '@models';
+
+import { deleteShareContent } from './delete';
+import { ensureShareContentIndexes } from './initialize';
+import { putShareContent } from './put';
+import { getShareContentContent, getShareContentRecovery, statShareContent } from './read';
+import { ShareContentRepositoryNotInitializedError } from './types';
+import type { ShareContentRepository } from './types';
+
+export * from './types';
+export { ensureShareContentIndexes, SHARE_CONTENT_IDENTITY_INDEX } from './initialize';
+
+/**
+ * Bind the dedicated `share_content` collection from a caller-provided `Db`.
+ * Deliberately does not import the service `@mongo` singleton, so nothing here
+ * opens a connection at import time and tests can inject a real/memory database.
+ */
+export const getShareContentCollection = (db: Db): Collection<MongoShareContentDocument> =>
+    db.collection<MongoShareContentDocument>(SHARE_CONTENT_COLLECTION);
+
+/**
+ * Build the narrow exact-object share-content repository over an injected
+ * collection.
+ *
+ * Operational contract:
+ * - `initialize()` must be awaited at startup; it installs the unique
+ *   `(namespace, objectId)` index. Every operation throws
+ *   {@link ShareContentRepositoryNotInitializedError} until then, so an
+ *   un-indexed database can never serve a write.
+ * - This repository is **not** an authorization boundary. The route batch must
+ *   verify the C1 service context (namespace/op/shareId/contentVersion/
+ *   ownerProfileId/objectId/operationId/requestHash) first, then pass the exact
+ *   verified tuple. The repository only enforces the data-level binding and the
+ *   active/tombstone state machine.
+ */
+export const createShareContentRepository = (
+    collection: Collection<MongoShareContentDocument>
+): ShareContentRepository => {
+    let initialized = false;
+
+    const requireInitialized = (): Collection<MongoShareContentDocument> => {
+        if (!initialized) throw new ShareContentRepositoryNotInitializedError();
+
+        return collection;
+    };
+
+    return {
+        collection,
+        initialize: async () => {
+            await ensureShareContentIndexes(collection);
+            initialized = true;
+        },
+        put: async (input: ShareContentPutInput) => putShareContent(requireInitialized(), input),
+        getContent: async (binding: ShareContentObjectBinding) =>
+            getShareContentContent(requireInitialized(), binding),
+        getRecovery: async (binding: ShareContentObjectBinding) =>
+            getShareContentRecovery(requireInitialized(), binding),
+        stat: async (binding: ShareContentObjectBinding) =>
+            statShareContent(requireInitialized(), binding),
+        delete: async (binding: ShareContentObjectBinding) =>
+            deleteShareContent(requireInitialized(), binding),
+    };
+};

package/src/accesslayer/share-content/initialize.ts

@@ -0,0 +1,24 @@
+import type { Collection } from 'mongodb';
+
+import type { MongoShareContentDocument } from '@models';
+
+/** Stable index name so operators can verify/report the installed index. */
+export const SHARE_CONTENT_IDENTITY_INDEX = 'share_content_identity_unique';
+
+/**
+ * Explicitly install the required indexes before any operation is served.
+ *
+ * The unique `(namespace, objectId)` index is what makes create-only writes and
+ * permanent tombstones atomic: without it, a duplicate `insertOne` would create a
+ * second document instead of failing closed. Index creation is awaited by
+ * {@link createShareContentRepository}.initialize; it is never left to an
+ * eventual background build.
+ */
+export const ensureShareContentIndexes = async (
+    collection: Collection<MongoShareContentDocument>
+): Promise<void> => {
+    await collection.createIndex(
+        { namespace: 1, objectId: 1 },
+        { unique: true, name: SHARE_CONTENT_IDENTITY_INDEX }
+    );
+};

package/src/accesslayer/share-content/internal.ts

@@ -0,0 +1,89 @@
+import type { Filter } from 'mongodb';
+
+import {
+    ShareContentObjectBindingValidator,
+    type MongoShareContentActive,
+    type MongoShareContentDocument,
+    type MongoShareContentTombstone,
+    type ShareContentObjectBinding,
+} from '@models';
+
+import type { ShareContentActiveSummary, ShareContentTombstoneSummary } from './types';
+
+/**
+ * Bounded retry count for the atomic insert/delete race loops. The state machine
+ * is monotonic (active -> tombstone, never back), so the loop always settles; the
+ * bound protects against a pathological unique-index/driver anomaly rather than
+ * ordinary contention.
+ */
+export const MAX_SHARE_CONTENT_ATTEMPTS = 5;
+
+export const parseShareContentBinding = (raw: unknown): ShareContentObjectBinding | null => {
+    const parsed = ShareContentObjectBindingValidator.safeParse(raw);
+
+    return parsed.success ? parsed.data : null;
+};
+
+/** Exact six-field binding filter. Missing any field would widen the query. */
+export const shareContentBindingFilter = (
+    binding: ShareContentObjectBinding
+): Filter<MongoShareContentDocument> => ({
+    namespace: binding.namespace,
+    ownerProfileId: binding.ownerProfileId,
+    shareId: binding.shareId,
+    contentVersion: binding.contentVersion,
+    objectId: binding.objectId,
+    operationId: binding.operationId,
+});
+
+/** Identity filter for the unique `(namespace, objectId)` index. */
+export const shareContentIdentityFilter = (
+    binding: Pick<ShareContentObjectBinding, 'namespace' | 'objectId'>
+): Filter<MongoShareContentDocument> => ({
+    namespace: binding.namespace,
+    objectId: binding.objectId,
+});
+
+export const bindingMatchesDocument = (
+    doc: MongoShareContentDocument,
+    binding: ShareContentObjectBinding
+): boolean =>
+    doc.namespace === binding.namespace &&
+    doc.ownerProfileId === binding.ownerProfileId &&
+    doc.shareId === binding.shareId &&
+    doc.contentVersion === binding.contentVersion &&
+    doc.objectId === binding.objectId &&
+    doc.operationId === binding.operationId;
+
+/** MongoDB duplicate-key error (unique index violation). */
+export const isDuplicateKeyError = (error: unknown): boolean =>
+    typeof error === 'object' && error !== null && (error as { code?: unknown }).code === 11000;
+
+export const toActiveSummary = (doc: MongoShareContentActive): ShareContentActiveSummary => ({
+    kind: 'active',
+    namespace: doc.namespace,
+    ownerProfileId: doc.ownerProfileId,
+    shareId: doc.shareId,
+    contentVersion: doc.contentVersion,
+    objectId: doc.objectId,
+    operationId: doc.operationId,
+    contentHash: doc.contentHash,
+    payloadHash: doc.payloadHash,
+    ciphertextBytes: doc.ciphertextBytes,
+    recoveryBytes: doc.recoveryBytes,
+    createdAt: doc.createdAt,
+});
+
+export const toTombstoneSummary = (
+    doc: MongoShareContentTombstone
+): ShareContentTombstoneSummary => ({
+    kind: 'tombstone',
+    namespace: doc.namespace,
+    ownerProfileId: doc.ownerProfileId,
+    shareId: doc.shareId,
+    contentVersion: doc.contentVersion,
+    objectId: doc.objectId,
+    operationId: doc.operationId,
+    ...(doc.contentHash === undefined ? {} : { contentHash: doc.contentHash }),
+    deletedAt: doc.deletedAt,
+});

package/src/accesslayer/share-content/put.ts

@@ -0,0 +1,93 @@
+import type { Collection } from 'mongodb';
+
+import {
+    ShareContentPutInputValidator,
+    computeShareContentHash,
+    computeSharePayloadHash,
+    measureShareContentPayload,
+    type MongoShareContentActive,
+    type MongoShareContentDocument,
+    type ShareContentPutInput,
+} from '@models';
+
+import {
+    MAX_SHARE_CONTENT_ATTEMPTS,
+    bindingMatchesDocument,
+    isDuplicateKeyError,
+    shareContentIdentityFilter,
+    toActiveSummary,
+} from './internal';
+import type { ShareContentPutResult } from './types';
+
+const buildActiveDocument = (
+    input: ShareContentPutInput,
+    contentHash: string
+): MongoShareContentActive => {
+    const { ciphertextBytes, recoveryBytes } = measureShareContentPayload(input);
+
+    return {
+        kind: 'active',
+        namespace: input.namespace,
+        ownerProfileId: input.ownerProfileId,
+        shareId: input.shareId,
+        contentVersion: input.contentVersion,
+        objectId: input.objectId,
+        operationId: input.operationId,
+        contentHash,
+        payloadHash: computeSharePayloadHash(input),
+        envelope: input.envelope,
+        ownerEncryptedRecovery: input.ownerEncryptedRecovery,
+        ciphertextBytes,
+        recoveryBytes,
+        createdAt: new Date(),
+    };
+};
+
+/**
+ * Create-only immutable write.
+ *
+ * The write is an atomic `insertOne` against the unique `(namespace, objectId)`
+ * index; there is no read-then-write window. On a duplicate key the existing
+ * document is classified: a tombstone is permanent, an active document with the
+ * same derived hash and all six bindings is an exact idempotent success, and
+ * anything else is a conflict. Because active documents are never replaced and
+ * tombstones are permanent, the classification read cannot be invalidated by a
+ * concurrent writer in a way that resurrects content.
+ */
+export const putShareContent = async (
+    collection: Collection<MongoShareContentDocument>,
+    rawInput: unknown
+): Promise<ShareContentPutResult> => {
+    const parsed = ShareContentPutInputValidator.safeParse(rawInput);
+
+    if (!parsed.success) return { ok: false, error: 'INVALID_INPUT' };
+
+    const input = parsed.data;
+    const contentHash = computeShareContentHash(input);
+
+    for (let attempt = 0; attempt < MAX_SHARE_CONTENT_ATTEMPTS; attempt += 1) {
+        const document = buildActiveDocument(input, contentHash);
+
+        try {
+            await collection.insertOne(document);
+
+            return { ok: true, value: { status: 'created', record: toActiveSummary(document) } };
+        } catch (error) {
+            if (!isDuplicateKeyError(error)) return { ok: false, error: 'STORE_ERROR' };
+        }
+
+        const existing = await collection.findOne(shareContentIdentityFilter(input));
+
+        if (existing === null) continue;
+
+        if (existing.kind === 'tombstone') return { ok: false, error: 'TOMBSTONED' };
+
+        if (existing.contentHash === contentHash && bindingMatchesDocument(existing, input)) {
+            return { ok: true, value: { status: 'idempotent', record: toActiveSummary(existing) } };
+        }
+
+        return { ok: false, error: 'CONFLICT' };
+    }
+
+    return { ok: false, error: 'CONFLICT' };
+};

package/src/accesslayer/share-content/read.ts

@@ -0,0 +1,124 @@
+import type { Collection } from 'mongodb';
+
+import type { MongoShareContentDocument } from '@models';
+
+import {
+    parseShareContentBinding,
+    shareContentBindingFilter,
+    toActiveSummary,
+    toTombstoneSummary,
+} from './internal';
+import type {
+    ShareContentContentProjection,
+    ShareContentRecoveryProjection,
+    ShareContentRepositoryResult,
+    ShareContentStatProjection,
+} from './types';
+
+/**
+ * Content projection for the exact active object. The owner recovery is never
+ * read into this projection. A missing object, a tombstone or any binding
+ * mismatch is reported as the same opaque `NOT_FOUND`, so the repository does
+ * not disclose another owner's object existence.
+ */
+export const getShareContentContent = async (
+    collection: Collection<MongoShareContentDocument>,
+    rawBinding: unknown
+): Promise<ShareContentRepositoryResult<ShareContentContentProjection>> => {
+    const binding = parseShareContentBinding(rawBinding);
+
+    if (binding === null) return { ok: false, error: 'INVALID_INPUT' };
+
+    const document = await collection.findOne(
+        { ...shareContentBindingFilter(binding), kind: 'active' },
+        { projection: { ownerEncryptedRecovery: 0 } }
+    );
+
+    if (document === null || document.kind !== 'active') return { ok: false, error: 'NOT_FOUND' };
+
+    return {
+        ok: true,
+        value: {
+            kind: 'active',
+            namespace: binding.namespace,
+            ownerProfileId: binding.ownerProfileId,
+            shareId: binding.shareId,
+            contentVersion: binding.contentVersion,
+            objectId: binding.objectId,
+            operationId: binding.operationId,
+            contentHash: document.contentHash,
+            payloadHash: document.payloadHash,
+            envelope: document.envelope,
+            ciphertextBytes: document.ciphertextBytes,
+            createdAt: document.createdAt,
+        },
+    };
+};
+
+/**
+ * Owner-only recovery projection for the exact active object. The ciphertext
+ * envelope is never read into this projection and the returned value carries no
+ * content bytes. The route layer must call this only after verifying the owner
+ * context; the repository is not an authorization boundary.
+ */
+export const getShareContentRecovery = async (
+    collection: Collection<MongoShareContentDocument>,
+    rawBinding: unknown
+): Promise<ShareContentRepositoryResult<ShareContentRecoveryProjection>> => {
+    const binding = parseShareContentBinding(rawBinding);
+
+    if (binding === null) return { ok: false, error: 'INVALID_INPUT' };
+
+    const document = await collection.findOne(
+        { ...shareContentBindingFilter(binding), kind: 'active' },
+        { projection: { envelope: 0, ciphertextBytes: 0 } }
+    );
+
+    if (document === null || document.kind !== 'active') return { ok: false, error: 'NOT_FOUND' };
+
+    return {
+        ok: true,
+        value: {
+            kind: 'active',
+            namespace: binding.namespace,
+            ownerProfileId: binding.ownerProfileId,
+            shareId: binding.shareId,
+            contentVersion: binding.contentVersion,
+            objectId: binding.objectId,
+            operationId: binding.operationId,
+            contentHash: document.contentHash,
+            payloadHash: document.payloadHash,
+            ownerEncryptedRecovery: document.ownerEncryptedRecovery,
+            recoveryBytes: document.recoveryBytes,
+            createdAt: document.createdAt,
+        },
+    };
+};
+
+/**
+ * Existence/hash/byte summary for the exact tuple. Returns the tombstone summary
+ * for a matching permanent tombstone (reconciliation needs it) and the opaque
+ * `NOT_FOUND` for any binding mismatch. No ciphertext or recovery is read.
+ */
+export const statShareContent = async (
+    collection: Collection<MongoShareContentDocument>,
+    rawBinding: unknown
+): Promise<ShareContentRepositoryResult<ShareContentStatProjection>> => {
+    const binding = parseShareContentBinding(rawBinding);
+
+    if (binding === null) return { ok: false, error: 'INVALID_INPUT' };
+
+    const document = await collection.findOne(shareContentBindingFilter(binding), {
+        projection: { envelope: 0, ownerEncryptedRecovery: 0 },
+    });
+
+    if (document === null) return { ok: false, error: 'NOT_FOUND' };
+
+    return {
+        ok: true,
+        value:
+            document.kind === 'tombstone'
+                ? toTombstoneSummary(document)
+                : toActiveSummary(document),
+    };
+};

package/src/accesslayer/share-content/types.ts

@@ -0,0 +1,155 @@
+import type { Collection } from 'mongodb';
+
+import type {
+    MongoShareContentDocument,
+    ShareContentHash,
+    ShareContentObjectBinding,
+    ShareContentPutInput,
+    ShareEnvelope,
+    ShareOwnerRecovery,
+} from '@models';
+
+/**
+ * Stable, non-secret repository result codes. Routes map every failure to a
+ * single generic external rejection; a repository error must never be returned
+ * verbatim to a caller.
+ */
+export type ShareContentRepositoryError =
+    'INVALID_INPUT' | 'NOT_FOUND' | 'TOMBSTONED' | 'BINDING_MISMATCH' | 'CONFLICT' | 'STORE_ERROR';
+
+export type ShareContentRepositoryFailure = { ok: false; error: ShareContentRepositoryError };
+
+export type ShareContentRepositoryResult<T> =
+    { ok: true; value: T } | ShareContentRepositoryFailure;
+
+/** `created` for the first write, `idempotent` for an exact retry. */
+export type ShareContentWriteStatus = 'created' | 'idempotent';
+
+/** Non-sensitive active summary; never includes ciphertext or recovery. */
+export type ShareContentActiveSummary = {
+    kind: 'active';
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+    contentHash: ShareContentHash;
+    payloadHash: ShareContentHash;
+    ciphertextBytes: number;
+    recoveryBytes: number;
+    createdAt: Date;
+};
+
+/** Tombstone summary retained after deletion. */
+export type ShareContentTombstoneSummary = {
+    kind: 'tombstone';
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+    contentHash?: ShareContentHash;
+    deletedAt: Date;
+};
+
+/**
+ * Content projection. The owner recovery is deliberately absent: it is only
+ * reachable through the separately authorized {@link
+ * ShareContentRepository.getRecovery} method.
+ */
+export type ShareContentContentProjection = {
+    kind: 'active';
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+    contentHash: ShareContentHash;
+    payloadHash: ShareContentHash;
+    envelope: ShareEnvelope;
+    ciphertextBytes: number;
+    createdAt: Date;
+};
+
+/**
+ * Owner-only recovery projection. The ciphertext envelope is absent. The route
+ * layer must call this only for an authenticated owner-recovery request; the
+ * repository is not an authorization boundary by itself.
+ */
+export type ShareContentRecoveryProjection = {
+    kind: 'active';
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+    contentHash: ShareContentHash;
+    payloadHash: ShareContentHash;
+    ownerEncryptedRecovery: ShareOwnerRecovery;
+    recoveryBytes: number;
+    createdAt: Date;
+};
+
+export type ShareContentStatProjection = ShareContentActiveSummary | ShareContentTombstoneSummary;
+
+/** Successful put value: `created` or an exact idempotent retry. */
+export type ShareContentPutResultValue = {
+    status: ShareContentWriteStatus;
+    record: ShareContentActiveSummary;
+};
+export type ShareContentPutResult = ShareContentRepositoryResult<ShareContentPutResultValue>;
+
+/**
+ * Narrow exact-object repository. There is deliberately no list, scan,
+ * wildcard or `deleteOwner` method: every call is bound to one immutable tuple.
+ *
+ * The repository enforces data-level bindings only. It is **not** an
+ * authorization boundary: callers must have already verified the C1 service
+ * authorization context (namespace/op/shareId/contentVersion/ownerProfileId/
+ * objectId/operationId/requestHash) before invoking it.
+ */
+export type ShareContentRepository = {
+    /** The injected collection. Useful for diagnostics; not a query surface. */
+    readonly collection: Collection<MongoShareContentDocument>;
+    /**
+     * Explicitly install the required unique identity index before serving any
+     * operation. Must be awaited during startup; index creation is never left to
+     * an eventual background build.
+     */
+    initialize: () => Promise<void>;
+    /** Create-only write. Same tuple + derived hash is an idempotent success. */
+    put: (input: ShareContentPutInput) => Promise<ShareContentPutResult>;
+    /** Content projection (no recovery) for the active object, or a failure. */
+    getContent: (
+        binding: ShareContentObjectBinding
+    ) => Promise<ShareContentRepositoryResult<ShareContentContentProjection>>;
+    /** Owner-only recovery projection for the active object, or a failure. */
+    getRecovery: (
+        binding: ShareContentObjectBinding
+    ) => Promise<ShareContentRepositoryResult<ShareContentRecoveryProjection>>;
+    /** Existence/hash/byte summary for the exact tuple (active or tombstone). */
+    stat: (
+        binding: ShareContentObjectBinding
+    ) => Promise<ShareContentRepositoryResult<ShareContentStatProjection>>;
+    /**
+     * Atomically tombstone the exact object. Deleting an absent identity writes a
+     * permanent tombstone first, so a late concurrent put can never resurrect it.
+     */
+    delete: (
+        binding: ShareContentObjectBinding
+    ) => Promise<ShareContentRepositoryResult<ShareContentTombstoneSummary>>;
+};
+
+/** Thrown when an operation is attempted before {@link ShareContentRepository.initialize}. */
+export class ShareContentRepositoryNotInitializedError extends Error {
+    readonly code = 'SHARE_CONTENT_REPOSITORY_NOT_INITIALIZED';
+
+    constructor() {
+        super('share-content repository must be initialized before serving operations');
+        this.name = 'ShareContentRepositoryNotInitializedError';
+    }
+}

package/src/config/environment.ts

@@ -29,6 +29,13 @@ export const learnCloudServiceEnvironmentShape = {
     IS_OFFLINE: optionalEnvironmentBoolean.default(false),
     SKIP_DIDKIT_NAPI: optionalEnvironmentBoolean.default(false),
     CI: optionalEnvironmentBoolean.default(false),
+    // LC-2187 service-only share-content routes. Available once an operator
+    // provisions an explicit audience, service DID allowlist, exact verification
+    // methods and per-service namespace bindings.
+    SHARE_CONTENT_AUDIENCE: optionalEnvironmentString,
+    SHARE_CONTENT_SERVICE_DIDS: optionalEnvironmentString,
+    SHARE_CONTENT_VERIFICATION_METHODS: optionalEnvironmentString,
+    SHARE_CONTENT_NAMESPACE_BINDINGS: optionalEnvironmentString,
 } satisfies z.ZodRawShape;
 
 export const learnCloudServiceEnvironmentSchema = z
@@ -56,6 +63,32 @@ export const learnCloudServiceEnvironmentSchema = z
                 message: 'RSA_PRIVATE_KEY and RSA_PUBLIC_KEY must be configured together',
             });
         }
+
+        if (
+            [
+                environment.SHARE_CONTENT_AUDIENCE,
+                environment.SHARE_CONTENT_SERVICE_DIDS,
+                environment.SHARE_CONTENT_VERIFICATION_METHODS,
+                environment.SHARE_CONTENT_NAMESPACE_BINDINGS,
+            ].some(Boolean)
+        ) {
+            const requiredShareContentFields = [
+                'SHARE_CONTENT_AUDIENCE',
+                'SHARE_CONTENT_SERVICE_DIDS',
+                'SHARE_CONTENT_VERIFICATION_METHODS',
+                'SHARE_CONTENT_NAMESPACE_BINDINGS',
+            ] as const;
+
+            for (const field of requiredShareContentFields) {
+                if (!environment[field]) {
+                    context.addIssue({
+                        code: 'custom',
+                        path: [field],
+                        message: 'Required when share-content service configuration is supplied',
+                    });
+                }
+            }
+        }
     });
 
 export type LearnCloudServiceEnvironment = z.output<typeof learnCloudServiceEnvironmentSchema>;

package/src/docker-entry.ts

@@ -11,6 +11,11 @@ import { openApiDocument } from './openapi';
 import { didFastifyPlugin } from './dids';
 import { xapiFastifyPlugin } from './xapi';
 import { oidcFastifyPlugin } from './oidc';
+import {
+    createShareContentRuntimeFromEnvironment,
+    registerShareContentRoutes,
+    type ShareContentRuntime,
+} from './share-content';
 
 const server = Fastify({ maxParamLength: 5000 });
 
@@ -52,10 +57,24 @@ server.register(xapiFastifyPlugin);
 server.register(oidcFastifyPlugin);
 
 (async () => {
+    let shareContentRuntime: ShareContentRuntime | null = null;
+
     try {
+        // Disabled by default: this performs no Mongo/Redis/index work unless an
+        // operator explicitly enables the routes with a valid configuration.
+        shareContentRuntime = await createShareContentRuntimeFromEnvironment();
+
+        if (shareContentRuntime.enabled) {
+            await registerShareContentRoutes(server, shareContentRuntime);
+        }
+
         console.log('Server starting on port ', environment.PORT || 3000);
         await server.listen({ host: '0.0.0.0', port: Number(environment.PORT || 3000) });
     } catch (err) {
+        if (shareContentRuntime?.enabled) {
+            await shareContentRuntime.close().catch(() => {});
+        }
+
         console.error(err);
         process.exit(1);
     }

package/src/helpers/share-content-auth/adapters.ts

@@ -0,0 +1,48 @@
+import type { PresentationVerificationResult, PresentationVerifier, ReplayStore } from './types';
+
+/**
+ * Thin, injectable adapters over the existing LearnCloud primitives.
+ *
+ * These are the seams the future service routes will wire. They are not
+ * registered anywhere in this batch: no router, no server entrypoint, no
+ * environment bootstrap.
+ */
+
+/** Minimal structural view of `getEmptyLearnCard()` for presentation verification. */
+export type LearnCardLike = {
+    invoke: {
+        verifyPresentation: (
+            token: string,
+            options: { proofFormat: 'jwt' }
+        ) => Promise<PresentationVerificationResult>;
+    };
+};
+
+/**
+ * Adapter for the existing DIDKit verification used by LearnCloud's context:
+ * `learnCard.invoke.verifyPresentation(jwt, { proofFormat: 'jwt' })`.
+ *
+ * This adapter is intentionally not constructed at import time and is not
+ * registered on any route in this batch.
+ */
+export const createDidkitPresentationVerifier = (
+    getLearnCard: () => Promise<LearnCardLike>
+): PresentationVerifier => {
+    return async (token: string) => {
+        const learnCard = await getLearnCard();
+
+        return learnCard.invoke.verifyPresentation(token, { proofFormat: 'jwt' });
+    };
+};
+
+/**
+ * `SET key value NX EX ttl` style atomic primitive. Must resolve `true` only
+ * when the key was absent and this call created it, and must throw when the
+ * store is unavailable.
+ */
+export type SetIfAbsent = (key: string, ttlSeconds: number) => Promise<boolean>;
+
+/** Adapt an atomic set-if-absent primitive (e.g. Redis) into a `ReplayStore`. */
+export const createSetIfAbsentReplayStore = (setIfAbsent: SetIfAbsent): ReplayStore => ({
+    consumeOnce: (key, ttlSeconds) => setIfAbsent(key, ttlSeconds),
+});