@learncard/learn-cloud-service 2.5.34 → 2.5.36

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/config/serverlessFunctionEnv.test.ts

@@ -0,0 +1,81 @@
+import { createRequire } from 'node:module';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const require = createRequire(import.meta.url);
+const functions: {
+    provider: (context?: {
+        options: { stage: string; httpPort?: string };
+    }) => Record<string, unknown>;
+} = require('../../serverless.function-env.cjs');
+
+beforeEach(() => {
+    vi.stubEnv('RUNTIME_SECRETS_ID', '');
+    vi.stubEnv('LEARN_CLOUD_SEED', 'seed');
+    vi.stubEnv('LEARN_CLOUD_MONGO_URI', 'mongodb://localhost:27017');
+    // XAPI_ENDPOINT is a user-classified bundle secret, so populate a stale fallback value
+    // to prove it never leaks onto the provider once a runtime bundle is configured.
+    vi.stubEnv('XAPI_ENDPOINT', 'https://stale.xapi.example.com');
+});
+afterEach(() => vi.unstubAllEnvs());
+
+describe('learn-cloud-service serverless function environments', () => {
+    it('omits all credential fallbacks in bundle mode', () => {
+        vi.stubEnv('RUNTIME_SECRETS_ID', 'learn-cloud-service/dev/runtime-secrets');
+        expect(Object.keys(functions.provider()).sort()).toEqual([
+            'CONFIG_TENANT',
+            'LAMBDA_STAGE',
+            'PORT',
+            'REDIS_HOST',
+            'REDIS_PORT',
+            'RUNTIME_SECRETS_ID',
+        ]);
+    });
+
+    it('drops the XAPI_ENDPOINT bundle secret in bundle mode even when a stale fallback is set', () => {
+        vi.stubEnv('RUNTIME_SECRETS_ID', 'learn-cloud-service/dev/runtime-secrets');
+        expect(functions.provider()).not.toHaveProperty('XAPI_ENDPOINT');
+    });
+
+    it('retains the existing provider credentials only in fallback mode', () => {
+        const provider = functions.provider();
+        expect(provider.LEARN_CLOUD_SEED).toBe('seed');
+        expect(provider.LEARN_CLOUD_MONGO_URI).toBe('mongodb://localhost:27017');
+        expect(provider.XAPI_ENDPOINT).toBe('https://stale.xapi.example.com');
+        expect(provider.RUNTIME_SECRETS_ID).toBeUndefined();
+    });
+
+    it('preserves the CloudFormation Redis intrinsics and CLI options', () => {
+        const provider = functions.provider({ options: { stage: 'production', httpPort: '5100' } });
+        expect(provider.LAMBDA_STAGE).toBe('production');
+        expect(provider.PORT).toBe('5100');
+        expect(provider.REDIS_HOST).toEqual({
+            'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Address'],
+        });
+        expect(provider.REDIS_PORT).toEqual({
+            'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Port'],
+        });
+    });
+
+    it.each(['', 'bundle'])(
+        'resolves the full provider environment through Serverless v3 (%s)',
+        async bundle => {
+            const source = require('serverless/lib/configuration/variables/sources/file');
+            vi.stubEnv('RUNTIME_SECRETS_ID', bundle);
+            const options = { stage: 'production', httpPort: '5100' };
+            const result = await source.resolve({
+                serviceDir: new URL('../../', import.meta.url).pathname,
+                params: [new URL('../../serverless.function-env.cjs', import.meta.url).pathname],
+                address: 'provider',
+                options,
+                resolveConfigurationProperty: vi.fn(),
+                resolveVariable: vi.fn(),
+            });
+            expect(result.value).toEqual(functions.provider({ options }));
+            expect(result.value.LAMBDA_STAGE).toBe('production');
+            expect(result.value.PORT).toBe('5100');
+            expect(result.value.REDIS_HOST).toEqual({
+                'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Address'],
+            });
+        }
+    );
+});

package/src/config/stageConfig.test.ts

@@ -0,0 +1,26 @@
+import { afterEach, expect, it, vi } from 'vitest';
+
+// Model a non-empty .env value arriving before the stage defaults are applied.
+vi.mock('dotenv/config', () => {
+    vi.stubEnv('SENTRY_ENV', 'self-hosted');
+    return {};
+});
+
+afterEach(() => vi.unstubAllEnvs());
+
+it('loads local env before applying statically imported stage defaults', async () => {
+    const { applyLearnCloudStageConfig, stages } = await import('./stageConfig');
+    for (const key of Object.keys(stages.dev)) {
+        if (key !== 'SENTRY_ENV') vi.stubEnv(key, '');
+    }
+    applyLearnCloudStageConfig('dev');
+    expect(process.env.SENTRY_ENV).toBe('self-hosted');
+    expect(process.env.SERVER_URL).toBe(stages.dev.SERVER_URL);
+});
+
+it('does not select a deployed stage for an unknown local stage', async () => {
+    const { applyLearnCloudStageConfig } = await import('./stageConfig');
+    vi.stubEnv('SERVER_URL', '');
+    applyLearnCloudStageConfig('unregistered-self-hosted-stage');
+    expect(process.env.SERVER_URL).toBe('');
+});

package/src/config/stageConfig.ts

@@ -0,0 +1,24 @@
+import 'dotenv/config';
+import { applyStageConfig } from '@learncard/service-config';
+
+import baseConfig from '../../config/config.json';
+import devConfig from '../../config/config.dev.json';
+import productionConfig from '../../config/config.production.json';
+import scoutsDevConfig from '../../config/config.scouts.dev.json';
+import scoutsProductionConfig from '../../config/config.scouts.production.json';
+
+export const base: Record<string, string> = baseConfig;
+
+export const stages = {
+    dev: devConfig,
+    production: productionConfig,
+    // ScoutPass deploys the same services and stage names; CONFIG_TENANT=scouts selects these.
+    'scouts.dev': scoutsDevConfig,
+    'scouts.production': scoutsProductionConfig,
+} satisfies Record<string, Record<string, string>>;
+
+// Must run before any module that reads configuration on import (e.g. @environment):
+// merges base + the selected stage into process.env; explicit non-empty env still wins.
+export const applyLearnCloudStageConfig = (stage: string | undefined): void => {
+    applyStageConfig({ base, stages, stage });
+};

package/src/docker-entry.ts

@@ -1,3 +1,5 @@
+import './config/applyDockerStageConfig';
+
 import { environment } from '@environment';
 import path from 'path';
 
@@ -11,6 +13,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 +59,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),
+});

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

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { canonicalizeShareContentRequestBody } from '@learncard/helpers';
+
+import { SHARE_CONTENT_OPERATIONS, type ShareContentOperation } from './types';
+
+/**
+ * Canonicalization / identifier primitives for the LC-2187 service auth module.
+ *
+ * Every value that reaches a hash or a comparison is validated here with strict
+ * (not permissive) rules. `Buffer.from(x, 'base64url')` is lenient, so the
+ * canonical base64url check re-encodes and requires an exact round trip, which
+ * rejects alternative spellings that merely decode to the same bytes.
+ */
+
+export {
+    canonicalizeShareContentRequestBody,
+    DEFAULT_MAX_CANONICAL_BYTES as DEFAULT_MAX_CANONICAL_REQUEST_BYTES,
+    DEFAULT_MAX_CANONICAL_DEPTH,
+    ShareContentCanonicalizationError,
+} from '@learncard/helpers';
+
+const BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
+const OPAQUE_IDENTIFIER_RE = /^[A-Za-z0-9._~-]+$/;
+const JTI_RE = /^[A-Za-z0-9_-]+$/;
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+
+export const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+    if (typeof value !== 'object' || value === null) return false;
+
+    const prototype = Object.getPrototypeOf(value);
+
+    return prototype === Object.prototype || prototype === null;
+};
+
+/** Strict canonical base64url: alphabet, no padding, exact round trip, optional byte length. */
+export const isCanonicalBase64Url = (value: unknown, expectedBytes?: number): value is string => {
+    if (typeof value !== 'string' || value.length === 0) return false;
+    if (!BASE64URL_RE.test(value)) return false;
+
+    const decoded = Buffer.from(value, 'base64url');
+
+    if (decoded.toString('base64url') !== value) return false;
+    if (expectedBytes !== undefined && decoded.length !== expectedBytes) return false;
+
+    return true;
+};
+
+export const isSafeContentVersion = (value: unknown): value is number =>
+    typeof value === 'number' && Number.isSafeInteger(value) && value >= 1 && value <= 2 ** 31 - 1;
+
+export const isSafeEpochSecond = (value: unknown): value is number =>
+    typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+
+/**
+ * Opaque profile/object/operation/namespace identifier. Deliberately not a UUID
+ * check: existing profile ids are opaque URL-safe strings.
+ */
+export const isOpaqueIdentifier = (value: unknown, maxLength = 128): value is string =>
+    typeof value === 'string' &&
+    value.length >= 1 &&
+    value.length <= maxLength &&
+    OPAQUE_IDENTIFIER_RE.test(value);
+
+export const isBoundedNonce = (
+    value: unknown,
+    minLength: number,
+    maxLength: number
+): value is string =>
+    typeof value === 'string' &&
+    value.length >= minLength &&
+    value.length <= maxLength &&
+    JTI_RE.test(value);
+
+export const isSha256Hex = (value: unknown): value is string =>
+    typeof value === 'string' && SHA256_HEX_RE.test(value);
+
+export const isShareContentOperation = (value: unknown): value is ShareContentOperation =>
+    typeof value === 'string' && (SHARE_CONTENT_OPERATIONS as readonly string[]).includes(value);
+
+/**
+ * SHA-256 (lowercase hex) over the canonical UTF-8 request body. This is the
+ * value signed into `claims.requestHash`; it must include the opaque ciphertext
+ * envelope and the opaque owner-encrypted recovery for `put`.
+ */
+export const computeShareContentRequestHash = (
+    body: unknown,
+    options: { maxBytes?: number; maxDepth?: number } = {}
+): string =>
+    createHash('sha256')
+        .update(canonicalizeShareContentRequestBody(body, options), 'utf8')
+        .digest('hex');

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

@@ -0,0 +1,164 @@
+import {
+    isBoundedNonce,
+    isCanonicalBase64Url,
+    isOpaqueIdentifier,
+    isPlainObject,
+    isSafeContentVersion,
+    isSafeEpochSecond,
+    isSha256Hex,
+    isShareContentOperation,
+} from './canonical';
+import {
+    SHARE_CONTENT_AUTH_PURPOSE,
+    SHARE_CONTENT_CLAIM_FIELDS,
+    type ShareContentAuthorizationClaims,
+    type ShareContentTrustConfig,
+} from './types';
+
+/** Share ids are 16 CSPRNG bytes → exactly 22 canonical base64url chars. */
+export const SHARE_ID_BYTES = 16;
+
+const MAX_OPAQUE_IDENTIFIER_LENGTH = 128;
+
+export type SignedClaimsResult =
+    { ok: true; raw: unknown } | { ok: false; reason: 'MALFORMED_CLAIMS' };
+
+/**
+ * Locate the JSON claims the holder signed. DIDKit serializes the presentation
+ * proof `challenge` into the JWT `nonce`; some clients surface it under
+ * `vp.proof.challenge`. Exactly one location/value must be present.
+ */
+export const extractSignedClaims = (payload: Record<string, unknown>): SignedClaimsResult => {
+    const nonce = payload.nonce;
+    const vp = payload.vp;
+
+    const proofChallenge =
+        isPlainObject(vp) && isPlainObject(vp.proof) ? vp.proof.challenge : undefined;
+
+    const candidates = [nonce, proofChallenge].filter(candidate => candidate !== undefined);
+
+    if (candidates.length === 0) return { ok: false, reason: 'MALFORMED_CLAIMS' };
+    if (candidates.length === 2 && candidates[0] !== candidates[1]) {
+        return { ok: false, reason: 'MALFORMED_CLAIMS' };
+    }
+
+    const challenge = candidates[0];
+
+    if (typeof challenge !== 'string' || challenge.length === 0) {
+        return { ok: false, reason: 'MALFORMED_CLAIMS' };
+    }
+
+    try {
+        return { ok: true, raw: JSON.parse(challenge) };
+    } catch {
+        return { ok: false, reason: 'MALFORMED_CLAIMS' };
+    }
+};
+
+export type ParseClaimsResult =
+    | { ok: true; claims: ShareContentAuthorizationClaims }
+    | {
+          ok: false;
+          reason:
+              | 'MALFORMED_CLAIMS'
+              | 'UNKNOWN_CLAIM_FIELD'
+              | 'INVALID_CLAIMS'
+              | 'INVALID_SHARE_ID'
+              | 'INVALID_IDENTIFIER'
+              | 'INVALID_JTI'
+              | 'OPERATION_NOT_ALLOWED'
+              | 'PURPOSE_MISMATCH';
+      };
+
+/**
+ * Strict structural validation of the signed claims. Audience/purpose/time and
+ * request binding are checked separately by the verifier so each has a distinct
+ * rejection reason.
+ */
+export const parseShareContentAuthorizationClaims = (
+    raw: unknown,
+    config: ShareContentTrustConfig
+): ParseClaimsResult => {
+    if (!isPlainObject(raw)) return { ok: false, reason: 'MALFORMED_CLAIMS' };
+
+    for (const key of Object.keys(raw)) {
+        if (!(SHARE_CONTENT_CLAIM_FIELDS as readonly string[]).includes(key)) {
+            return { ok: false, reason: 'UNKNOWN_CLAIM_FIELD' };
+        }
+    }
+
+    const {
+        iss,
+        aud,
+        purpose,
+        namespace,
+        op,
+        shareId,
+        contentVersion,
+        ownerProfileId,
+        objectId,
+        operationId,
+        requestHash,
+        iat,
+        exp,
+        jti,
+    } = raw;
+
+    if (typeof iss !== 'string' || iss.length === 0) return { ok: false, reason: 'INVALID_CLAIMS' };
+    if (typeof aud !== 'string' || aud.length === 0) return { ok: false, reason: 'INVALID_CLAIMS' };
+    if (purpose !== SHARE_CONTENT_AUTH_PURPOSE) return { ok: false, reason: 'PURPOSE_MISMATCH' };
+
+    if (!isOpaqueIdentifier(namespace, MAX_OPAQUE_IDENTIFIER_LENGTH)) {
+        return { ok: false, reason: 'INVALID_IDENTIFIER' };
+    }
+
+    if (!isShareContentOperation(op)) return { ok: false, reason: 'OPERATION_NOT_ALLOWED' };
+
+    if (!isCanonicalBase64Url(shareId, SHARE_ID_BYTES)) {
+        return { ok: false, reason: 'INVALID_SHARE_ID' };
+    }
+
+    if (!isSafeContentVersion(contentVersion)) return { ok: false, reason: 'INVALID_CLAIMS' };
+
+    if (!isOpaqueIdentifier(ownerProfileId, MAX_OPAQUE_IDENTIFIER_LENGTH)) {
+        return { ok: false, reason: 'INVALID_IDENTIFIER' };
+    }
+
+    if (!isOpaqueIdentifier(objectId, MAX_OPAQUE_IDENTIFIER_LENGTH)) {
+        return { ok: false, reason: 'INVALID_IDENTIFIER' };
+    }
+
+    if (!isOpaqueIdentifier(operationId, MAX_OPAQUE_IDENTIFIER_LENGTH)) {
+        return { ok: false, reason: 'INVALID_IDENTIFIER' };
+    }
+
+    if (!isSha256Hex(requestHash)) return { ok: false, reason: 'INVALID_CLAIMS' };
+
+    if (!isSafeEpochSecond(iat) || !isSafeEpochSecond(exp)) {
+        return { ok: false, reason: 'INVALID_CLAIMS' };
+    }
+
+    if (!isBoundedNonce(jti, config.minJtiLength, config.maxJtiLength)) {
+        return { ok: false, reason: 'INVALID_JTI' };
+    }
+
+    return {
+        ok: true,
+        claims: {
+            iss,
+            aud,
+            purpose: SHARE_CONTENT_AUTH_PURPOSE,
+            namespace,
+            op,
+            shareId,
+            contentVersion,
+            ownerProfileId,
+            objectId,
+            operationId,
+            requestHash,
+            iat,
+            exp,
+            jti,
+        },
+    };
+};

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

@@ -0,0 +1,160 @@
+import type { ShareContentTrustConfig } from './types';
+
+/**
+ * Build the trust configuration from an explicit, caller-supplied object.
+ *
+ * Nothing here reads `process.env`, secrets or a bootstrap file: the batch that
+ * owns environment wiring must construct this deliberately and pass it in. Any
+ * missing or invalid value when `enabled` is true collapses to the disabled
+ * configuration so access fails closed rather than partially.
+ */
+
+export const HARD_MAX_TOKEN_TTL_SECONDS = 60;
+export const HARD_MAX_CLOCK_SKEW_SECONDS = 60;
+export const HARD_MIN_TOKEN_BYTES = 256;
+export const HARD_MAX_TOKEN_BYTES = 65_536;
+export const DEFAULT_MAX_TOKEN_BYTES = 8_192;
+export const DEFAULT_MIN_JTI_LENGTH = 16;
+export const DEFAULT_MAX_JTI_LENGTH = 128;
+
+export const DISABLED_SHARE_CONTENT_TRUST_CONFIG: ShareContentTrustConfig = Object.freeze({
+    enabled: false,
+    audience: '',
+    allowedServiceDids: Object.freeze([]) as readonly string[],
+    allowedVerificationMethods: Object.freeze([]) as readonly string[],
+    allowedAlgorithms: Object.freeze(['EdDSA']) as readonly string[],
+    clockSkewSeconds: 5,
+    maxTokenTtlSeconds: HARD_MAX_TOKEN_TTL_SECONDS,
+    maxTokenBytes: DEFAULT_MAX_TOKEN_BYTES,
+    minJtiLength: DEFAULT_MIN_JTI_LENGTH,
+    maxJtiLength: DEFAULT_MAX_JTI_LENGTH,
+});
+
+const toStringList = (value: unknown): string[] | null => {
+    if (typeof value === 'string') {
+        const parts = value
+            .split(',')
+            .map(part => part.trim())
+            .filter(part => part.length > 0);
+
+        return parts;
+    }
+
+    if (Array.isArray(value)) {
+        if (!value.every(item => typeof item === 'string')) return null;
+
+        const parts = (value as string[]).map(part => part.trim()).filter(part => part.length > 0);
+
+        return parts;
+    }
+
+    return null;
+};
+
+const readBoolean = (value: unknown): boolean => value === true;
+
+const readBoundedInteger = (
+    value: unknown,
+    fallback: number,
+    minimum: number,
+    maximum: number
+): number | null => {
+    if (value === undefined) return fallback;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value)) return null;
+    if (value < minimum || value > maximum) return null;
+
+    return value;
+};
+
+/**
+ * Resolve explicit configuration. Returns the frozen, fully-validated config or
+ * the disabled config. An empty allowlist, empty audience or `enabled: false`
+ * disables all access.
+ */
+export const resolveShareContentTrustConfig = (raw: unknown): ShareContentTrustConfig => {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return DISABLED_SHARE_CONTENT_TRUST_CONFIG;
+    }
+
+    const source = raw as Record<string, unknown>;
+
+    if (!readBoolean(source.enabled)) return DISABLED_SHARE_CONTENT_TRUST_CONFIG;
+
+    const audience = source.audience;
+    if (typeof audience !== 'string' || audience.trim().length === 0) {
+        return DISABLED_SHARE_CONTENT_TRUST_CONFIG;
+    }
+
+    const serviceDids = toStringList(source.serviceDids);
+    const verificationMethods = toStringList(source.verificationMethods);
+
+    if (!serviceDids || serviceDids.length === 0) return DISABLED_SHARE_CONTENT_TRUST_CONFIG;
+    if (!verificationMethods || verificationMethods.length === 0) {
+        return DISABLED_SHARE_CONTENT_TRUST_CONFIG;
+    }
+
+    const allowedAlgorithms = toStringList(source.allowedAlgorithms) ?? ['EdDSA'];
+    if (allowedAlgorithms.length === 0) return DISABLED_SHARE_CONTENT_TRUST_CONFIG;
+
+    const clockSkewSeconds = readBoundedInteger(
+        source.clockSkewSeconds,
+        DISABLED_SHARE_CONTENT_TRUST_CONFIG.clockSkewSeconds,
+        0,
+        HARD_MAX_CLOCK_SKEW_SECONDS
+    );
+    const maxTokenTtlSeconds = readBoundedInteger(
+        source.maxTokenTtlSeconds,
+        HARD_MAX_TOKEN_TTL_SECONDS,
+        1,
+        HARD_MAX_TOKEN_TTL_SECONDS
+    );
+    const maxTokenBytes = readBoundedInteger(
+        source.maxTokenBytes,
+        DEFAULT_MAX_TOKEN_BYTES,
+        HARD_MIN_TOKEN_BYTES,
+        HARD_MAX_TOKEN_BYTES
+    );
+    const minJtiLength = readBoundedInteger(
+        source.minJtiLength,
+        DEFAULT_MIN_JTI_LENGTH,
+        8,
+        DEFAULT_MAX_JTI_LENGTH
+    );
+    const maxJtiLength = readBoundedInteger(
+        source.maxJtiLength,
+        DEFAULT_MAX_JTI_LENGTH,
+        DEFAULT_MIN_JTI_LENGTH,
+        512
+    );
+
+    if (
+        clockSkewSeconds === null ||
+        maxTokenTtlSeconds === null ||
+        maxTokenBytes === null ||
+        minJtiLength === null ||
+        maxJtiLength === null ||
+        minJtiLength > maxJtiLength
+    ) {
+        return DISABLED_SHARE_CONTENT_TRUST_CONFIG;
+    }
+
+    return Object.freeze({
+        enabled: true,
+        audience,
+        allowedServiceDids: Object.freeze([...serviceDids]),
+        allowedVerificationMethods: Object.freeze([...verificationMethods]),
+        allowedAlgorithms: Object.freeze([...allowedAlgorithms]),
+        clockSkewSeconds,
+        maxTokenTtlSeconds,
+        maxTokenBytes,
+        minJtiLength,
+        maxJtiLength,
+    });
+};
+
+/** A config only authorizes traffic when it is enabled and its allowlists are non-empty. */
+export const isShareContentTrustConfigActive = (config: ShareContentTrustConfig): boolean =>
+    config.enabled &&
+    config.audience.length > 0 &&
+    config.allowedServiceDids.length > 0 &&
+    config.allowedVerificationMethods.length > 0;