@learncard/learn-cloud-service 2.5.34 → 2.5.35

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

@@ -0,0 +1,195 @@
+/**
+ * LC-2187 — Brain → LearnCloud share-content service authorization types.
+ *
+ * This module is a reusable authorization *verifier foundation*. It is not
+ * registered on any router and it does not read the environment. Callers inject
+ * the trust configuration, the presentation verifier, the clock and the atomic
+ * replay store, so the unit tests exercise the real module without Redis,
+ * MongoDB, did:web resolution or unfinished storage/schema work.
+ */
+
+/** Signed purpose claim. V1 is the only accepted value. */
+export const SHARE_CONTENT_AUTH_PURPOSE = 'lc-share-content/v1' as const;
+
+/**
+ * Least-privilege operation allowlist. There is deliberately no `list`,
+ * `deleteOwner` or other wildcard/collection-wide privilege: every token is
+ * bound to exactly one immutable object. `readRecovery` is the separate
+ * owner-encrypted recovery read intent.
+ */
+export const SHARE_CONTENT_OPERATIONS = ['put', 'get', 'stat', 'delete', 'readRecovery'] as const;
+
+export type ShareContentOperation = (typeof SHARE_CONTENT_OPERATIONS)[number];
+
+/** Every key that may appear in the signed claims object. Unknown keys are rejected. */
+export const SHARE_CONTENT_CLAIM_FIELDS = [
+    'iss',
+    'aud',
+    'purpose',
+    'namespace',
+    'op',
+    'shareId',
+    'contentVersion',
+    'ownerProfileId',
+    'objectId',
+    'operationId',
+    'requestHash',
+    'iat',
+    'exp',
+    'jti',
+] as const;
+
+export type ShareContentClaimField = (typeof SHARE_CONTENT_CLAIM_FIELDS)[number];
+
+/** Claims signed by Brain and re-validated by LearnCloud. */
+export type ShareContentAuthorizationClaims = {
+    /** Issuer = holder = the allowlisted Brain service DID. */
+    iss: string;
+    /** LearnCloud service DID. */
+    aud: string;
+    purpose: typeof SHARE_CONTENT_AUTH_PURPOSE;
+    /** Service/network namespace (tenant or deployment scope). */
+    namespace: string;
+    op: ShareContentOperation;
+    /** 16-byte canonical base64url share id (22 chars). */
+    shareId: string;
+    contentVersion: number;
+    /** Opaque profile id. Existing ids are opaque strings, not necessarily UUIDs. */
+    ownerProfileId: string;
+    /** Immutable object identity for this exact content version. */
+    objectId: string;
+    /** Operation/idempotency identity. */
+    operationId: string;
+    /** Lowercase hex SHA-256 of the canonical full request body, incl. opaque recovery. */
+    requestHash: string;
+    iat: number;
+    exp: number;
+    /** CSPRNG nonce; single-use. */
+    jti: string;
+};
+
+/**
+ * The exact request context the token must be bound to. Callers build this from
+ * the validated route input; `requestHash` is produced with
+ * `computeShareContentRequestHash`.
+ */
+export type ShareContentAuthorizationRequest = {
+    namespace: string;
+    op: ShareContentOperation;
+    shareId: string;
+    contentVersion: number;
+    ownerProfileId: string;
+    objectId: string;
+    operationId: string;
+    requestHash: string;
+};
+
+/** Minimal authenticated context returned on success. Never contains the raw token. */
+export type ShareContentAuthorizationContext = {
+    signerDid: string;
+    /** Full `kid` verification method that signed the presentation. */
+    verificationMethod: string;
+    claims: ShareContentAuthorizationClaims;
+};
+
+/** Result shape of the existing DIDKit `verifyPresentation(..., { proofFormat: 'jwt' })`. */
+export type PresentationVerificationResult = {
+    checks: string[];
+    warnings: string[];
+    errors: string[];
+};
+
+/** Injected DIDKit adapter. The module never resolves keys itself. */
+export type PresentationVerifier = (token: string) => Promise<PresentationVerificationResult>;
+
+/**
+ * Injected atomic replay store. `consumeOnce` must be a single atomic
+ * SET-if-absent (e.g. Redis `SET key value NX EX ttl`) and must throw when the
+ * backing store is unavailable so the verifier can fail closed.
+ */
+export type ReplayStore = {
+    consumeOnce: (key: string, ttlSeconds: number) => Promise<boolean>;
+};
+
+/**
+ * Explicit trust configuration. An empty/disabled configuration denies all
+ * access (fail closed). There is deliberately no offline bypass flag.
+ *
+ * Key rotation assumptions (document-backed, not yet integration-tested):
+ * - A `did:web` identifier is stable across signing-seed rotation; the
+ *   verification method fragment in the JWT `kid` is what changes.
+ * - Operators must add the new verification method to
+ *   `allowedVerificationMethods` *before* the new key signs, and keep the old
+ *   entry for at least `maxTokenTtlSeconds + 2 * clockSkewSeconds` after the
+ *   last token signed by the old key.
+ * - did:web DID-document/resolver cache propagation must be validated in the
+ *   integration batch; this module never resolves a DID itself.
+ */
+export type ShareContentTrustConfig = {
+    enabled: boolean;
+    /** LearnCloud's own service DID. Must be non-empty when enabled. */
+    audience: string;
+    /** Exact allowed Brain service DIDs. A user DID must never be listed. */
+    allowedServiceDids: readonly string[];
+    /**
+     * Exact allowed verification methods (full `kid` values). Required: a DID
+     * alone does not authorize a key. Empty disables access.
+     */
+    allowedVerificationMethods: readonly string[];
+    /** Accepted JWS algorithms. Defaults to `EdDSA` only. */
+    allowedAlgorithms: readonly string[];
+    /** Bounded clock skew, seconds. */
+    clockSkewSeconds: number;
+    /** Maximum signed lifetime (`exp - iat`), seconds. Never above 60. */
+    maxTokenTtlSeconds: number;
+    /** Maximum raw token size in bytes. */
+    maxTokenBytes: number;
+    minJtiLength: number;
+    maxJtiLength: number;
+};
+
+/**
+ * Rejection reasons are stable, non-secret codes. Routes must map every one of
+ * them to a single generic external rejection; they must never be logged
+ * alongside token or claim payloads.
+ */
+export type ShareContentAuthorizationRejectionReason =
+    | 'DISABLED'
+    | 'INVALID_REQUEST'
+    | 'TOKEN_TOO_LARGE'
+    | 'MALFORMED_TOKEN'
+    | 'UNSUPPORTED_HEADER'
+    | 'UNSUPPORTED_ALGORITHM'
+    | 'MISSING_KID'
+    | 'UNKNOWN_SIGNER'
+    | 'UNKNOWN_VERIFICATION_METHOD'
+    | 'SIGNATURE_INVALID'
+    | 'SIGNER_MISMATCH'
+    | 'MALFORMED_CLAIMS'
+    | 'UNKNOWN_CLAIM_FIELD'
+    | 'INVALID_CLAIMS'
+    | 'INVALID_SHARE_ID'
+    | 'INVALID_IDENTIFIER'
+    | 'INVALID_JTI'
+    | 'AUDIENCE_MISMATCH'
+    | 'PURPOSE_MISMATCH'
+    | 'OPERATION_NOT_ALLOWED'
+    | 'INVALID_TTL'
+    | 'TOKEN_EXPIRED'
+    | 'TOKEN_NOT_YET_VALID'
+    | 'REQUEST_BINDING_MISMATCH'
+    | 'REQUEST_HASH_MISMATCH'
+    | 'REPLAY_DETECTED'
+    | 'REPLAY_STORE_UNAVAILABLE';
+
+export type ShareContentAuthorizationResult =
+    | { ok: true; context: ShareContentAuthorizationContext }
+    | { ok: false; reason: ShareContentAuthorizationRejectionReason };
+
+export type ShareContentAuthorizationVerifier = {
+    config: ShareContentTrustConfig;
+    authorize: (
+        request: ShareContentAuthorizationRequest,
+        token: string
+    ) => Promise<ShareContentAuthorizationResult>;
+};

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

@@ -0,0 +1,220 @@
+import { createHash } from 'node:crypto';
+
+import {
+    isCanonicalBase64Url,
+    isOpaqueIdentifier,
+    isPlainObject,
+    isSafeContentVersion,
+    isSha256Hex,
+    isShareContentOperation,
+} from './canonical';
+import {
+    SHARE_ID_BYTES,
+    extractSignedClaims,
+    parseShareContentAuthorizationClaims,
+} from './claims';
+import { isShareContentTrustConfigActive } from './config';
+import { parseCompactJwt, validateShareContentJwtHeader } from './token';
+import {
+    SHARE_CONTENT_AUTH_PURPOSE,
+    type PresentationVerificationResult,
+    type PresentationVerifier,
+    type ReplayStore,
+    type ShareContentAuthorizationContext,
+    type ShareContentAuthorizationRequest,
+    type ShareContentAuthorizationResult,
+    type ShareContentAuthorizationVerifier,
+    type ShareContentTrustConfig,
+} from './types';
+
+export type CreateShareContentAuthorizationVerifierDependencies = {
+    config: ShareContentTrustConfig;
+    /** Injected DIDKit presentation verification. Never called before allowlist filtering. */
+    verifyPresentation: PresentationVerifier;
+    /** Injected atomic single-use replay store. */
+    replayStore: ReplayStore;
+    /** Injected epoch-seconds clock. Defaults to `Date.now()`. */
+    now?: () => number;
+};
+
+const isValidAuthorizationRequest = (
+    request: unknown
+): request is ShareContentAuthorizationRequest => {
+    if (!isPlainObject(request)) return false;
+
+    const {
+        namespace,
+        op,
+        shareId,
+        contentVersion,
+        ownerProfileId,
+        objectId,
+        operationId,
+        requestHash,
+    } = request;
+
+    return (
+        isOpaqueIdentifier(namespace) &&
+        isShareContentOperation(op) &&
+        isCanonicalBase64Url(shareId, SHARE_ID_BYTES) &&
+        isSafeContentVersion(contentVersion) &&
+        isOpaqueIdentifier(ownerProfileId) &&
+        isOpaqueIdentifier(objectId) &&
+        isOpaqueIdentifier(operationId) &&
+        isSha256Hex(requestHash)
+    );
+};
+
+const isSignatureValid = (verification: PresentationVerificationResult | undefined): boolean =>
+    Boolean(
+        verification &&
+        Array.isArray(verification.errors) &&
+        Array.isArray(verification.checks) &&
+        verification.errors.length === 0 &&
+        verification.checks.includes('JWS')
+    );
+
+/**
+ * Build an authorization verifier over a fixed trust configuration.
+ *
+ * The returned `authorize(request, token)` is the only public entry point. It:
+ *   1. denies everything when the configuration is empty/disabled;
+ *   2. validates the expected request context;
+ *   3. strictly parses the bounded JWT and applies the exact DID + key-method
+ *      allowlist *before* calling the signature verifier;
+ *   4. cryptographically verifies, then re-binds kid → signer DID → `iss` →
+ *      `vp.holder` → signed `claims.iss`;
+ *   5. validates purpose/audience/operation/time/nonce and exact request
+ *      binding (including the canonical body hash);
+ *   6. atomically consumes the nonce for the full remaining acceptance window,
+ *      failing closed if the replay store errors.
+ *
+ * A fresh signed token (new `jti`) may retry the same idempotent operation;
+ * request idempotency is a separate concern owned by the storage layer.
+ */
+export const createShareContentAuthorizationVerifier = (
+    dependencies: CreateShareContentAuthorizationVerifierDependencies
+): ShareContentAuthorizationVerifier => {
+    const { config, verifyPresentation, replayStore } = dependencies;
+    const now = dependencies.now ?? (() => Math.floor(Date.now() / 1000));
+
+    const authorize = async (
+        request: ShareContentAuthorizationRequest,
+        token: string
+    ): Promise<ShareContentAuthorizationResult> => {
+        if (!isShareContentTrustConfigActive(config)) return { ok: false, reason: 'DISABLED' };
+        if (!isValidAuthorizationRequest(request)) return { ok: false, reason: 'INVALID_REQUEST' };
+
+        const parseResult = parseCompactJwt(token, config.maxTokenBytes);
+        if (!parseResult.ok) return parseResult;
+
+        const headerResult = validateShareContentJwtHeader(parseResult.parsed.header, config);
+        if (!headerResult.ok) return headerResult;
+
+        const { signerDid, verificationMethod } = headerResult.value;
+
+        let verification: PresentationVerificationResult;
+
+        try {
+            verification = await verifyPresentation(token);
+        } catch {
+            return { ok: false, reason: 'SIGNATURE_INVALID' };
+        }
+
+        if (!isSignatureValid(verification)) return { ok: false, reason: 'SIGNATURE_INVALID' };
+
+        const { payload } = parseResult.parsed;
+
+        // Recheck every identity claim against the key that actually signed,
+        // after cryptographic verification. Parsing alone never authenticates.
+        if (payload.iss !== signerDid) return { ok: false, reason: 'SIGNER_MISMATCH' };
+
+        const vp = payload.vp;
+        if (!isPlainObject(vp) || vp.holder !== signerDid) {
+            return { ok: false, reason: 'SIGNER_MISMATCH' };
+        }
+
+        const claimsResult = extractSignedClaims(payload);
+        if (!claimsResult.ok) return claimsResult;
+
+        const parsedClaims = parseShareContentAuthorizationClaims(claimsResult.raw, config);
+        if (!parsedClaims.ok) return parsedClaims;
+
+        const claims = parsedClaims.claims;
+
+        if (claims.iss !== signerDid) return { ok: false, reason: 'SIGNER_MISMATCH' };
+        if (claims.aud !== config.audience) return { ok: false, reason: 'AUDIENCE_MISMATCH' };
+        if (claims.purpose !== SHARE_CONTENT_AUTH_PURPOSE) {
+            return { ok: false, reason: 'PURPOSE_MISMATCH' };
+        }
+
+        const currentTime = now();
+        if (!Number.isSafeInteger(currentTime)) return { ok: false, reason: 'INVALID_TTL' };
+
+        const signedTtl = claims.exp - claims.iat;
+        if (signedTtl <= 0 || signedTtl > config.maxTokenTtlSeconds) {
+            return { ok: false, reason: 'INVALID_TTL' };
+        }
+
+        const { clockSkewSeconds } = config;
+
+        if (currentTime > claims.exp + clockSkewSeconds)
+            return { ok: false, reason: 'TOKEN_EXPIRED' };
+        if (claims.iat > currentTime + clockSkewSeconds) {
+            return { ok: false, reason: 'TOKEN_NOT_YET_VALID' };
+        }
+
+        // Exact expected context must match the signed claims before any replay
+        // consumption, so a mismatched request can never burn a valid nonce.
+        if (
+            claims.namespace !== request.namespace ||
+            claims.op !== request.op ||
+            claims.shareId !== request.shareId ||
+            claims.contentVersion !== request.contentVersion ||
+            claims.ownerProfileId !== request.ownerProfileId ||
+            claims.objectId !== request.objectId ||
+            claims.operationId !== request.operationId
+        ) {
+            return { ok: false, reason: 'REQUEST_BINDING_MISMATCH' };
+        }
+
+        if (claims.requestHash !== request.requestHash) {
+            return { ok: false, reason: 'REQUEST_HASH_MISMATCH' };
+        }
+
+        // Replay protection covers the whole acceptance window (expiry + skew).
+        // `iat` may itself be up to `skew` in the future, so the maximum
+        // derivable lifetime is maxTtl + 2 * skew.
+        const replayTtlSeconds = claims.exp + clockSkewSeconds - currentTime;
+        const maxReplayTtlSeconds = config.maxTokenTtlSeconds + 2 * clockSkewSeconds;
+
+        if (replayTtlSeconds <= 0 || replayTtlSeconds > maxReplayTtlSeconds) {
+            return { ok: false, reason: 'INVALID_TTL' };
+        }
+
+        const replayKey = `share-content-auth:jti:${createHash('sha256')
+            .update(`${signerDid}\u0000${claims.jti}`, 'utf8')
+            .digest('hex')}`;
+
+        let consumed: boolean;
+
+        try {
+            consumed = await replayStore.consumeOnce(replayKey, replayTtlSeconds);
+        } catch {
+            // Fail closed: an unavailable replay store must never widen access.
+            return { ok: false, reason: 'REPLAY_STORE_UNAVAILABLE' };
+        }
+
+        if (!consumed) return { ok: false, reason: 'REPLAY_DETECTED' };
+
+        const context: ShareContentAuthorizationContext = {
+            signerDid,
+            verificationMethod,
+            claims,
+        };
+
+        return { ok: true, context };
+    };
+
+    return { config, authorize };
+};

package/src/models/ShareContent.ts

@@ -0,0 +1,198 @@
+import { z } from 'zod';
+import {
+    JWEValidator,
+    MAX_SHARE_CIPHERTEXT_BYTES,
+    MAX_SHARE_RECOVERY_JWE_BYTES,
+    ShareEnvelopeValidator,
+    ShareLinkIdValidator,
+    ShareOwnerRecoveryValidator,
+    decodedBase64UrlByteLength,
+    type ShareEnvelope,
+    type ShareOwnerRecovery,
+    utf8ByteLength,
+} from '@learncard/types';
+
+import {
+    computeShareContentRequestHash,
+    isOpaqueIdentifier,
+    isSafeContentVersion,
+} from '@helpers/share-content-auth/canonical';
+
+/**
+ * LC-2187 dedicated LearnCloud `share_content` collection.
+ *
+ * This module defines the *storage* grammar for an immutable encrypted share
+ * object plus its permanent deletion tombstone. It is deliberately separate
+ * from the recipient manifest owners in `@learncard/types`: it never models
+ * plaintext, source URIs or keys, only opaque bindings and the already-encrypted
+ * envelope/recovery bytes.
+ *
+ * Security invariants encoded here:
+ * - The immutable identity is `(namespace, objectId)`. Every other binding
+ *   (`ownerProfileId`, `shareId`, `contentVersion`, `operationId`) is part of
+ *   the exact tuple and must match on every read/mutation.
+ * - `contentHash` is *derived* by {@link computeShareContentHash} over the full
+ *   validated immutable record (all bindings plus the ciphertext envelope and
+ *   the owner-encrypted recovery). A caller-supplied hash is never accepted, so
+ *   a forged hash cannot mask divergent bytes.
+ * - The recovery projection is deliberately owner-only at the route layer. The
+ *   stored recovery JWE is strict at the top level: unknown metadata/URL fields
+ *   are rejected, not persisted.
+ * - Bound sizes: decoded ciphertext (tag included) is at most
+ *   {@link MAX_SHARE_CIPHERTEXT_BYTES}; the serialized recovery JWE is at most
+ *   {@link MAX_SHARE_RECOVERY_JWE_BYTES}.
+ */
+
+/** MongoDB collection name for immutable encrypted share content. */
+export const SHARE_CONTENT_COLLECTION = 'share_content';
+
+const SHARE_CONTENT_HASH_PATTERN = /^[0-9a-f]{64}$/;
+
+/** Opaque, URL-safe binding identifier. Deliberately not a UUID-only check. */
+const opaqueIdentifier = (label: string, maxLength = 128) =>
+    z.string().refine(value => isOpaqueIdentifier(value, maxLength), {
+        message: `${label} must be an opaque URL-safe identifier of 1..${maxLength} characters`,
+    });
+
+/** Service/network/tenant namespace. Opaque; not a URL or host. */
+export const ShareContentNamespaceValidator = opaqueIdentifier('namespace');
+export type ShareContentNamespace = z.infer<typeof ShareContentNamespaceValidator>;
+
+/** Opaque owner profile id (existing ids are opaque strings, not necessarily UUIDs). */
+export const ShareContentOwnerProfileIdValidator = opaqueIdentifier('ownerProfileId');
+export type ShareContentOwnerProfileId = z.infer<typeof ShareContentOwnerProfileIdValidator>;
+
+/** Opaque immutable object id reserved by Brain. Never a URI. */
+export const ShareContentObjectIdValidator = opaqueIdentifier('objectId');
+export type ShareContentObjectId = z.infer<typeof ShareContentObjectIdValidator>;
+
+/** Opaque operation/idempotency id that owns the immutable object. */
+export const ShareContentOperationIdValidator = opaqueIdentifier('operationId');
+export type ShareContentOperationId = z.infer<typeof ShareContentOperationIdValidator>;
+
+/** Positive safe-integer content version (`1..2^31-1`). */
+export const ShareContentVersionValidator = z
+    .number()
+    .refine(isSafeContentVersion, { message: 'contentVersion must be a safe integer >= 1' });
+export type ShareContentContentVersion = z.infer<typeof ShareContentVersionValidator>;
+
+/** Lowercase hex SHA-256 of the derived immutable record. */
+export const ShareContentHashValidator = z
+    .string()
+    .regex(SHARE_CONTENT_HASH_PATTERN, { message: 'contentHash must be lowercase hex sha256' });
+export type ShareContentHash = z.infer<typeof ShareContentHashValidator>;
+
+/**
+ * Strict top-level owner recovery JWE. Wraps the shared
+ * {@link ShareOwnerRecoveryValidator} (which enforces the serialized 64 KiB cap)
+ * and additionally rejects unknown top-level keys so arbitrary metadata or URLs
+ * can never be persisted alongside the opaque recovery.
+ */
+export const ShareContentOwnerRecoveryValidator = JWEValidator.strict().refine(
+    value => ShareOwnerRecoveryValidator.safeParse(value).success,
+    { message: 'must be a valid bounded owner-encrypted recovery JWE' }
+);
+export type ShareContentOwnerRecovery = z.infer<typeof ShareContentOwnerRecoveryValidator>;
+
+/**
+ * The exact, immutable object binding. The repository applies this to every
+ * operation; a mutation of any single field fails closed.
+ */
+export const ShareContentObjectBindingValidator = z
+    .object({
+        namespace: ShareContentNamespaceValidator,
+        ownerProfileId: ShareContentOwnerProfileIdValidator,
+        shareId: ShareLinkIdValidator,
+        contentVersion: ShareContentVersionValidator,
+        objectId: ShareContentObjectIdValidator,
+        operationId: ShareContentOperationIdValidator,
+    })
+    .strict();
+export type ShareContentObjectBinding = z.infer<typeof ShareContentObjectBindingValidator>;
+
+/**
+ * A create-only write. `contentHash` is intentionally absent: the repository
+ * derives it, so a caller cannot supply (and therefore cannot forge) it.
+ */
+export const ShareContentPutInputValidator = ShareContentObjectBindingValidator.extend({
+    envelope: ShareEnvelopeValidator,
+    ownerEncryptedRecovery: ShareContentOwnerRecoveryValidator,
+}).strict();
+export type ShareContentPutInput = z.infer<typeof ShareContentPutInputValidator>;
+
+/**
+ * Derive the content hash over the complete immutable record: all bindings plus
+ * the validated ciphertext envelope and the owner-encrypted recovery. The C1
+ * canonical serializer makes the result deterministic and rejects unsupported
+ * values instead of coercing them.
+ */
+export const computeShareContentHash = (input: ShareContentPutInput): string =>
+    computeShareContentRequestHash({
+        namespace: input.namespace,
+        ownerProfileId: input.ownerProfileId,
+        shareId: input.shareId,
+        contentVersion: input.contentVersion,
+        objectId: input.objectId,
+        operationId: input.operationId,
+        envelope: input.envelope,
+        ownerEncryptedRecovery: input.ownerEncryptedRecovery,
+    });
+
+/** Hash known before Brain allocates object/operation IDs; reservation binding. */
+export const computeSharePayloadHash = (
+    input: Pick<ShareContentPutInput, 'envelope' | 'ownerEncryptedRecovery'>
+): string =>
+    computeShareContentRequestHash({
+        envelope: input.envelope,
+        ownerEncryptedRecovery: input.ownerEncryptedRecovery,
+    });
+
+/**
+ * Measure the encoded payload for reconciliation/stats. Assumes `input` already
+ * passed {@link ShareContentPutInputValidator}.
+ */
+export const measureShareContentPayload = (
+    input: Pick<ShareContentPutInput, 'envelope' | 'ownerEncryptedRecovery'>
+): { ciphertextBytes: number; recoveryBytes: number } => {
+    const ciphertextBytes = decodedBase64UrlByteLength(input.envelope.ct);
+
+    if (ciphertextBytes === null) {
+        throw new Error('validated envelope ciphertext must be canonical base64url');
+    }
+
+    return {
+        ciphertextBytes,
+        recoveryBytes: utf8ByteLength(JSON.stringify(input.ownerEncryptedRecovery)),
+    };
+};
+
+/** Immutable active document. */
+export const MongoShareContentActiveValidator = ShareContentObjectBindingValidator.extend({
+    kind: z.literal('active'),
+    contentHash: ShareContentHashValidator,
+    payloadHash: ShareContentHashValidator,
+    envelope: ShareEnvelopeValidator,
+    ownerEncryptedRecovery: ShareContentOwnerRecoveryValidator,
+    ciphertextBytes: z.number().int().min(16).max(MAX_SHARE_CIPHERTEXT_BYTES),
+    recoveryBytes: z.number().int().min(1).max(MAX_SHARE_RECOVERY_JWE_BYTES),
+    createdAt: z.date(),
+}).strict();
+export type MongoShareContentActive = z.infer<typeof MongoShareContentActiveValidator>;
+
+/**
+ * Permanent deletion tombstone. Retains the binding tuple and, where known, the
+ * derived hash; never retains ciphertext or recovery. A tombstone blocks every
+ * later put for the same `(namespace, objectId)` identity.
+ */
+export const MongoShareContentTombstoneValidator = ShareContentObjectBindingValidator.extend({
+    kind: z.literal('tombstone'),
+    contentHash: ShareContentHashValidator.optional(),
+    deletedAt: z.date(),
+}).strict();
+export type MongoShareContentTombstone = z.infer<typeof MongoShareContentTombstoneValidator>;
+
+/** Stored document union. */
+export type MongoShareContentDocument = MongoShareContentActive | MongoShareContentTombstone;
+
+/** Raw ciphertext envelope carried by an active object. */
+export type { ShareEnvelope, ShareOwnerRecovery };

package/src/models/index.ts

@@ -1,4 +1,5 @@
 export * from './Credential';
 export * from './CredentialRecord';
 export * from './CustomDocument';
+export * from './ShareContent';
 export * from './User';