@volter/twin-linkedin 0.1.0

package/dist/src/linkedin-twin.js

@@ -0,0 +1,1220 @@
+// The LinkedIn Community Management surface an organization POSTS through, twinned: an org's
+// company page, the admin's access control, the Posts API (create, get, batch get, find by author,
+// delete), the Images API and the Videos API (initialize, the signed-URL upload PUTs, finalize, and
+// the asset read that walks PROCESSING to AVAILABLE), the follower count, and the member's OpenID
+// userinfo — offline, against local state.
+//
+// SCOPE. What this pack exists for: a company posts release videos to its LinkedIn page, and each
+// post must be previewable as linkedin.com shows it before a gated deploy sends it. So the write half
+// is an organization's post with commentary and one image, one video or an article; the read half is
+// everything a page (and the mirror, linkedin-mirror-ui.ts) needs to show it. Comments, reactions,
+// social metadata, polls, multi-image, documents, reshares, targeting, dark posts, member (person)
+// posting and every analytics surface are real LinkedIn this pack does not model: each has a
+// manifest todo, and a request that reaches one is refused by name (linkedin-errors.ts `unmodeled`).
+//
+// GROUNDING. learn.microsoft.com/linkedin, the Marketing (li-lms) pages at version 202609, read for
+// this build: Posts API and Post Schema, Images API, Videos API, Organization Access Control by
+// Role, Organization Lookup (incl. networkSizes), Versioning, Error Responses, Rate Limiting, and
+// Sign In with LinkedIn using OpenID Connect (userinfo). Shapes below quote those pages' samples.
+//
+// VERSIONED. Every `/rest` call must carry `Linkedin-Version: YYYYMM`; a missing header is the
+// vendor's 400 VERSION_MISSING and a version outside the active set its 426 NONEXISTENT_VERSION.
+// The active set is the one the docs' version selector lists on 2026-09-26 (202510 … 202609; there
+// is no 202512). `/v2/userinfo` is the unversioned OpenID surface and takes no version.
+//
+// STATE. Subjects are stored in LinkedIn's own response shape (architecture "shape parity"):
+// a post IS its `GET /rest/posts/{urn}` body, keyed by its URN, with bookkeeping under `_` fields
+// that never reach the wire. Uploaded assets are not kernel state (linkedin-media.ts explains why).
+//
+// DETERMINISM. Every served answer is a function of (request, stored state). Times are the write's
+// `occurredAt`; a video's processing is a fold of its finalize instant and the request's (PROCESSING_MS), never a timer and never a read that writes.
+import { applyTwinWrite, applyTwinWriteAtomic, blobDigest, ownFields, projectResources, resolveSubjectId, subjectAliases } from '@volter/world-core';
+import { accessDenied, emptyAccessToken, invalidAccessToken, invalidUrnId, invalidUrnType, invalidValue, missingField, noContent, notFound, ok, problem, readOnlyRefusal, unmodeled, versionInactive, versionMissing, } from "./linkedin-errors.js";
+import { aspectRatio, clearParts, isAssetId, listAssetIds, MAX_IMAGE_PIXELS, MAX_VIDEO_BYTES, MAX_VIDEO_MS, MIN_VIDEO_BYTES, MIN_VIDEO_MS, putLinkedinBlob, putPart, readAsset, readPart, assetAsOf, newUploadSecret, signUpload, withAsset, assetIsOwn, hasUploadSecret, sniffImage, sniffVideo, UPLOAD_URL_LIFETIME_MS, verifyUpload, VIDEO_PART_BYTES, writeAsset, } from "./linkedin-media.js";
+const SERVICE = 'linkedin';
+/** The API versions LinkedIn serves on 2026-09-26 (the versioned docs' moniker list). */
+export const ACTIVE_VERSIONS = ['202510', '202511', '202601', '202602', '202603', '202604', '202605', '202606', '202607', '202608', '202609'];
+/** LinkedIn's own hosts, minted when no served base is known. */
+const UPLOAD_HOST = 'https://www.linkedin.com';
+const IMAGE_HOST = 'https://media.licdn.com';
+const VIDEO_HOST = 'https://dms.licdn.com';
+/** Post ids are 19-digit numbers inside a URN. A minted id must never collide with one PULLED from
+ *  the real vendor and never come from a row count: scan every id held and step past the highest,
+ *  starting above today's real id space (~7.3e18 in 2026). */
+const POST_ID_FLOOR = 9000000000000000000n;
+/** Twin-minted asset ids: `C5T10AQ` + a 12-digit ordinal — the vendor's length, a prefix no real
+ *  asset carries, so a pulled asset id and a minted one cannot meet. */
+const ASSET_PREFIX = 'C5T10AQ';
+// ── the documented closed sets ──────────────────────────────────────────────────────────────
+/** OAuth scopes a seeded token may carry — the permissions these pages name. */
+const SCOPES_DOCUMENTED = new Set([
+    'w_organization_social', 'r_organization_social', 'rw_organization_admin', 'r_organization_admin',
+    'w_member_social', 'r_member_social', 'rw_ads', 'r_ads', 'openid', 'profile', 'email',
+]);
+/** Organization Access Control by Role: the role types and role states. */
+const ROLES = new Set(['ADMINISTRATOR', 'DIRECT_SPONSORED_CONTENT_POSTER', 'RECRUITING_POSTER', 'LEAD_CAPTURE_ADMINISTRATOR', 'LEAD_GEN_FORMS_MANAGER', 'ANALYST', 'CURATOR', 'CONTENT_ADMINISTRATOR']);
+const ROLE_STATES = new Set(['APPROVED', 'REJECTED', 'REQUESTED', 'REVOKED']);
+/** Posts API permissions table: w/r_organization_social are "restricted to organizations where the
+ *  authenticated member has one of the following company page roles". */
+const POSTING_ROLES = new Set(['ADMINISTRATOR', 'DIRECT_SPONSORED_CONTENT_POSTER', 'CONTENT_ADMINISTRATOR']);
+/** Post Schema: `visibility` (MemberNetworkVisibility) and `distribution.feedDistribution`. */
+const VISIBILITIES = new Set(['CONNECTIONS', 'PUBLIC', 'LOGGED_IN', 'CONTAINER']);
+const FEED_DISTRIBUTIONS = new Set(['NONE', 'MAIN_FEED']);
+/** Post Schema: the content kinds. `media` and `article` are modelled. */
+const CONTENT_KINDS = new Set(['media', 'poll', 'multiImage', 'article', 'carousel', 'celebration', 'reference']);
+const POST_FIELDS = new Set([
+    'author', 'adContext', 'commentary', 'container', 'content', 'contentLandingPage', 'contentCallToActionLabel', 'distribution',
+    'isReshareDisabledByAuthor', 'lifecycleState', 'lifecycleStateInfo', 'publishedAt', 'reshareContext', 'visibility',
+]);
+// ── helpers ─────────────────────────────────────────────────────────────────────────────────
+function parseJson(body) {
+    if (body === undefined || body.trim() === '')
+        return { object: {} };
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return { malformed: true };
+        return { object: parsed };
+    }
+    catch {
+        return { malformed: true };
+    }
+}
+function header(headers, name) {
+    if (!headers)
+        return undefined;
+    for (const [k, v] of Object.entries(headers))
+        if (k.toLowerCase() === name)
+            return v;
+    return undefined;
+}
+function resources(root) {
+    return projectResources(SERVICE, root);
+}
+const ofType = (all, type) => all.filter((r) => r.type === type);
+const fields = (r) => ownFields(r);
+const nowMs = (req) => Date.parse(req.occurredAt ?? new Date().toISOString());
+const at = (req) => req.occurredAt ?? new Date().toISOString();
+const ORG_URN = /^urn:li:organization:(\d{1,19})$/;
+const PERSON_URN = /^urn:li:person:([A-Za-z0-9_-]{1,40})$/;
+const POST_URN = /^urn:li:(share|ugcPost):(\d{1,19})$/;
+const IMAGE_URN = /^urn:li:image:([A-Za-z0-9_-]{8,40})$/;
+const VIDEO_URN = /^urn:li:video:([A-Za-z0-9_-]{8,40})$/;
+/** A URN from a path segment or a query value: percent-decoded once (Rest.li protocol 2.0.0). */
+function urnFrom(raw) {
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+/** `List(a,b,c)` — Rest.li 2.0's list syntax in a query value. */
+function restliList(raw) {
+    if (raw === null)
+        return undefined;
+    const m = /^List\((.*)\)$/.exec(raw.trim());
+    if (!m)
+        return undefined;
+    return m[1].split(',').map((v) => urnFrom(v.trim())).filter((v) => v !== '');
+}
+// ── the little text format: hashtags ─────────────────────────────────────────────────────────
+// The Posts API "Hashtag a keyword" sample posts `Follow best practices #coding` and reads back
+// `Follow best practices {hashtag|\#|coding}`: LinkedIn stores a hashtag as the little-format
+// template. The twin applies the same rewrite on write, so the stored commentary is what LinkedIn
+// would answer. A `#` already inside a template, or glued to a word, is left alone.
+export function templateHashtags(commentary) {
+    return commentary.replace(/(^|[\s(])#([\p{L}\p{N}_]+)/gu, (_m, lead, tag) => `${lead}{hashtag|\\#|${tag}}`);
+}
+function authorize(all, headers) {
+    const raw = header(headers, 'authorization');
+    const match = raw ? /^Bearer\s+(\S+)\s*$/i.exec(raw.trim()) : null;
+    if (!match)
+        return emptyAccessToken();
+    const row = ofType(all, 'token').find((t) => String(t.id) === match[1]);
+    if (!row)
+        return invalidAccessToken();
+    const f = fields(row);
+    return { token: match[1], member: String(f.member), scopes: new Set(Array.isArray(f.scopes) ? f.scopes.map(String) : []) };
+}
+const isResponse = (v) => typeof v === 'object' && v !== null && 'status' in v && 'body' in v;
+function needScope(auth, anyOf, what) {
+    if (anyOf.some((s) => auth.scopes.has(s)))
+        return undefined;
+    return accessDenied(`Not enough permissions to access: ${what}. This token holds none of: ${anyOf.join(', ')}`);
+}
+/** The approved roles `member` holds on `organization` (both URNs). */
+function rolesOn(all, member, organization) {
+    const out = new Set();
+    for (const acl of ofType(all, 'organization_acl')) {
+        const f = fields(acl);
+        if (f.roleAssignee === member && f.organization === organization && f.state === 'APPROVED')
+            out.add(String(f.role));
+    }
+    return out;
+}
+function canPostAs(all, auth, organization) {
+    return [...rolesOn(all, auth.member, organization)].some((r) => POSTING_ROLES.has(r));
+}
+function versionGate(headers) {
+    const version = header(headers, 'linkedin-version');
+    if (version === undefined || version.trim() === '')
+        return versionMissing();
+    if (!ACTIVE_VERSIONS.includes(version.trim()))
+        return versionInactive(version.trim());
+    return undefined;
+}
+// ── ids ───────────────────────────────────────────────────────────────────────────────────────
+/**
+ * A new post URN, 19 digits in 9.0e18 … 9.2e18 (above today's real id space): a digest of the write
+ * itself — its instant, author and body, and the posts the tree already holds — re-drawn with the next
+ * attempt number while any held post id, or any local id a landing re-keyed to the vendor's URN (an
+ * alias), matches. So a URN a client was once answered is never handed out again; two clones of one
+ * World that each post before either pushes mint different URNs (their posts differ in instant or
+ * body), where a high-water mark + 1 gave both the same next URN and the origin one clone's post under
+ * the other's; and two identical fresh worlds replaying the same writes serve the same URNs (R9).
+ */
+function mintPostUrn(all, root, seed) {
+    const taken = new Set(ofType(all, 'post').map((p) => String(p.id)));
+    for (const key of subjectAliases(SERVICE, root).keys())
+        if (key.startsWith('post:'))
+            taken.add(key.slice('post:'.length));
+    for (let attempt = 0;; attempt += 1) {
+        const digest = blobDigest(new TextEncoder().encode(`${seed}|${taken.size}|${attempt}`));
+        const n = POST_ID_FLOOR + BigInt(`0x${digest.slice(0, 16)}`) % 200000000000000000n;
+        const urn = `urn:li:share:${n}`;
+        if (!taken.has(urn))
+            return urn;
+    }
+}
+/** A new asset id: `C5T10AQ` + 12 digits of entropy, re-drawn while any id this branch or its
+ *  ancestors hold matches. Entropy, not an ordinal: an ordinal collides between sibling branches, a
+ *  parent minting after its child, and two processes on one root; a random draw collides with none. */
+async function mintAssetId(root) {
+    const held = new Set(await listAssetIds(root));
+    for (;;) {
+        const digits = crypto.getRandomValues(new Uint32Array(2));
+        const id = `${ASSET_PREFIX}${String(digits[0] % 1_000_000).padStart(6, '0')}${String(digits[1] % 1_000_000).padStart(6, '0')}`;
+        if (!held.has(id))
+            return id;
+    }
+}
+// ── projection: THE one place a stored subject becomes a response body ────────────────────────
+/** A stored post as LinkedIn answers it: its vendor fields, no `_` bookkeeping. */
+export function projectPost(post) {
+    const f = fields(post);
+    const out = {};
+    for (const [k, v] of Object.entries(f))
+        if (!k.startsWith('_'))
+            out[k] = v;
+    out.id = String(post.id);
+    return out;
+}
+/** Deleted here, or tombstoned by the kernel from a refresh (`deleted: true`). */
+const isDeleted = (post) => fields(post)._deleted === true || fields(post).deleted === true;
+/** A post by the URN a client presented: resolved through the aliases at the request boundary, so a
+ *  local URN still reads the post after a landing re-keyed it to the vendor's. */
+function findPost(all, urn, root) {
+    const id = resolveSubjectId(SERVICE, 'post', urn, root);
+    return ofType(all, 'post').find((p) => String(p.id) === id);
+}
+function livePost(all, urn, root) {
+    const post = findPost(all, urn, root);
+    return post && !isDeleted(post) ? post : undefined;
+}
+function orgNumber(urn) {
+    const m = ORG_URN.exec(urn);
+    return m ? Number(m[1]) : undefined;
+}
+function findOrg(all, id) {
+    return ofType(all, 'organization').find((o) => String(o.id) === id);
+}
+/** The non-admin fields (Organization Lookup: "APIs that don't require administrative access will
+ *  only return" id, name, localizedName, localizedWebsite, vanityName, logoV2, locations,
+ *  primaryOrganizationType). */
+function projectOrgPublic(org) {
+    const f = fields(org);
+    return {
+        id: Number(org.id),
+        name: { localized: { en_US: String(f.localizedName) }, preferredLocale: { country: 'US', language: 'en' } },
+        localizedName: String(f.localizedName),
+        ...(typeof f.localizedWebsite === 'string' ? { localizedWebsite: f.localizedWebsite } : {}),
+        vanityName: String(f.vanityName),
+        ...(typeof f.logo === 'string' ? { logoV2: { cropped: f.logo, original: f.logo, cropInfo: { x: 0, y: 0, width: 0, height: 0 } } } : {}),
+        locations: [],
+        primaryOrganizationType: 'NONE',
+    };
+}
+/** The administered organization: the public fields plus the admin-only ones this twin holds. */
+function projectOrgAdmin(org) {
+    const f = fields(org);
+    return {
+        ...projectOrgPublic(org),
+        ...(typeof f.localizedDescription === 'string'
+            ? { localizedDescription: f.localizedDescription, description: { localized: { en_US: f.localizedDescription }, preferredLocale: { country: 'US', language: 'en' } } }
+            : {}),
+        ...(typeof f.localizedWebsite === 'string' ? { website: { localized: { en_US: f.localizedWebsite }, preferredLocale: { country: 'US', language: 'en' } } } : {}),
+        ...(Array.isArray(f.industries) ? { industries: f.industries } : {}),
+        defaultLocale: { country: 'US', language: 'en' },
+        $URN: `urn:li:organization:${org.id}`,
+    };
+}
+function parsePaging(url, defaultCount, maxCount) {
+    const rawStart = url.searchParams.get('start');
+    const rawCount = url.searchParams.get('count');
+    const start = rawStart === null ? 0 : Number(rawStart);
+    const count = rawCount === null ? defaultCount : Number(rawCount);
+    if (!Number.isInteger(start) || start < 0)
+        return invalidValue('start', rawStart);
+    if (!Number.isInteger(count) || count < 1 || count > maxCount)
+        return invalidValue('count', rawCount);
+    return { start, count };
+}
+/** A finder page: `{ paging: { start, count, links }, elements }`, with the vendor's `next` link. */
+function finderPage(elements, paging, url) {
+    const slice = elements.slice(paging.start, paging.start + paging.count);
+    const links = [];
+    if (paging.start + paging.count < elements.length) {
+        const next = new URLSearchParams(url.searchParams);
+        next.set('start', String(paging.start + paging.count));
+        next.set('count', String(paging.count));
+        links.push({ type: 'application/json', rel: 'next', href: `${url.pathname}?${next.toString()}` });
+    }
+    return ok({ paging: { start: paging.start, count: paging.count, links }, elements: slice });
+}
+// organizationAcls ─────────────────────────────────────────────────────────────────────────────
+function findAcls(all, auth, url) {
+    const refusal = needScope(auth, ['rw_organization_admin', 'r_organization_admin'], 'organizationAcls');
+    if (refusal)
+        return refusal;
+    const q = url.searchParams.get('q');
+    const role = url.searchParams.get('role');
+    const state = url.searchParams.get('state');
+    if (role !== null && !ROLES.has(role))
+        return invalidValue('role', role);
+    if (state !== null && !ROLE_STATES.has(state))
+        return invalidValue('state', state);
+    const paging = parsePaging(url, 10, 100);
+    if (isResponse(paging))
+        return paging;
+    const acls = ofType(all, 'organization_acl').map(fields)
+        .filter((f) => (role === null || f.role === role) && (state === null || f.state === state))
+        .sort((a, b) => `${a.organization}|${a.role}`.localeCompare(`${b.organization}|${b.role}`));
+    if (q === 'roleAssignee') {
+        // "Find a Member's Organization Access Control Information": the authenticated member's own.
+        const mine = acls.filter((f) => f.roleAssignee === auth.member)
+            .map((f) => ({ role: f.role, organization: f.organization, roleAssignee: f.roleAssignee, state: f.state }));
+        return finderPage(mine, paging, url);
+    }
+    if (q === 'organization') {
+        const organization = url.searchParams.get('organization');
+        if (organization === null)
+            return missingField('organization');
+        if (!ORG_URN.test(organization))
+            return invalidUrnType('organization', organization, 'organization');
+        if (!rolesOn(all, auth.member, organization).has('ADMINISTRATOR')) {
+            return accessDenied(`Not enough permissions to access: organizationAcls for ${organization}`);
+        }
+        const theirs = acls.filter((f) => f.organization === organization)
+            .map((f) => ({ state: f.state, role: f.role, roleAssignee: f.roleAssignee, organizationTarget: f.organization }));
+        return finderPage(theirs, paging, url);
+    }
+    if (q === null)
+        return missingField('q');
+    return invalidValue('q', q);
+}
+// organizations ───────────────────────────────────────────────────────────────────────────────
+function getOrganization(all, auth, id) {
+    const refusal = needScope(auth, ['rw_organization_admin', 'r_organization_admin'], 'organizations');
+    if (refusal)
+        return refusal;
+    if (!/^\d{1,19}$/.test(id))
+        return invalidUrnId(id);
+    const org = findOrg(all, id);
+    if (!org)
+        return notFound(`Organization ${id} is inactive`);
+    // "Retrieve an Administered Organization": a caller without the ADMINISTRATOR role gets 403.
+    if (!rolesOn(all, auth.member, `urn:li:organization:${id}`).has('ADMINISTRATOR')) {
+        return accessDenied(`Viewer don't have permission to the ADMIN_ONLY VisibilityReduction for urn:li:organization:${id}`);
+    }
+    return ok(projectOrgAdmin(org));
+}
+function findOrganizations(all, url) {
+    const q = url.searchParams.get('q');
+    if (q === 'vanityName') {
+        const vanity = url.searchParams.get('vanityName');
+        if (vanity === null || vanity.trim() === '')
+            return missingField('vanityName');
+        // "All strings are case-insensitive."
+        const hits = ofType(all, 'organization').filter((o) => String(fields(o).vanityName).toLowerCase() === vanity.trim().toLowerCase());
+        return ok({ paging: { start: 0, count: 10, links: [], total: hits.length }, elements: hits.map(projectOrgPublic) });
+    }
+    if (q === 'parentOrganization')
+        return unmodeled('The parentOrganization finder on /rest/organizations');
+    if (q === null) {
+        if (url.searchParams.get('ids') !== null)
+            return unmodeled('Batch get of /rest/organizations');
+        return missingField('q');
+    }
+    return invalidValue('q', q);
+}
+/** organizationsLookup?ids=List(...): organizations the member need not administer, with only the
+ *  non-admin fields, as a batch (`results` / `statuses` / `errors`). */
+function lookupOrganizations(all, url) {
+    const ids = restliList(url.searchParams.get('ids'));
+    if (ids === undefined)
+        return missingField('ids');
+    const results = {};
+    const statuses = {};
+    const errors = {};
+    for (const id of ids) {
+        const org = /^\d{1,19}$/.test(id) ? findOrg(all, id) : undefined;
+        if (!org) {
+            statuses[id] = 404;
+            errors[id] = { status: 404, code: 'NOT_FOUND', message: `Organization ${id} is inactive` };
+            continue;
+        }
+        results[id] = projectOrgPublic(org);
+        statuses[id] = 200;
+    }
+    return ok({ results, statuses, errors });
+}
+function networkSize(all, rawUrn, url) {
+    const urn = urnFrom(rawUrn);
+    const edgeType = url.searchParams.get('edgeType');
+    if (edgeType === null)
+        return missingField('edgeType');
+    // COMPANY_FOLLOWED_BY_MEMBER from v202305; the older CompanyFollowedByMember is not retrocompatible.
+    if (edgeType !== 'COMPANY_FOLLOWED_BY_MEMBER')
+        return invalidValue('edgeType', edgeType);
+    const id = orgNumber(urn);
+    if (id === undefined)
+        return invalidUrnType('networkSizes key', urn, 'organization');
+    const org = findOrg(all, String(id));
+    if (!org)
+        return notFound(`Organization ${id} is inactive`);
+    const size = fields(org).followerCount;
+    return ok({ firstDegreeSize: typeof size === 'number' ? size : 0 });
+}
+/** A content asset URN, resolved to a usable asset of `owner` — or the vendor's refusal. */
+async function resolveAsset(field, urn, owner, allowVideo, atMs, root) {
+    if (typeof urn !== 'string' || urn === '')
+        return missingField(field);
+    const image = IMAGE_URN.exec(urn);
+    const video = VIDEO_URN.exec(urn);
+    if (!image && !(allowVideo && video)) {
+        if (/^urn:li:document:/.test(urn))
+            return unmodeled('Document content (urn:li:document) on a post');
+        return invalidUrnType(field, urn, allowVideo ? 'image or video' : 'image');
+    }
+    const stored = await readAsset((image ?? video)[1], root);
+    if (!stored || stored.kind !== (image ? 'image' : 'video'))
+        return invalidUrnId(urn);
+    const asset = assetAsOf(stored, atMs);
+    if (asset.owner !== owner)
+        return accessDenied(`Accessing this ${asset.kind} resource is forbidden. Please check your permissions for this resource`);
+    if (asset.status === 'WAITING_UPLOAD')
+        return problem(400, 'MEDIA_ASSET_WAITING_UPLOAD', 'Media asset is waiting upload');
+    if (asset.status === 'PROCESSING_FAILED')
+        return problem(400, 'MEDIA_ASSET_PROCESSING_FAILED', 'Media asset failed processing');
+    // LinkedIn would accept a still-processing video and hold the post at PUBLISH_REQUESTED; the twin
+    // does not model that lifecycle (linkedin.posts.publish_requested) and refuses rather than pretend.
+    if (asset.status !== 'AVAILABLE')
+        return unmodeled('A post naming a video that is still PROCESSING (the PUBLISH_REQUESTED lifecycle)');
+    return { kind: image ? 'image' : 'video', asset };
+}
+function assetBookkeeping(media) {
+    const a = media.asset;
+    return {
+        kind: media.kind, id: a.id, owner: a.owner, sha256: a.sha256, size: a.size, media_type: a.media_type,
+        ...(a.width !== undefined ? { width: a.width, height: a.height } : {}),
+        ...(a.duration_ms !== undefined ? { duration_ms: a.duration_ms } : {}),
+        ...(a.thumbnail_sha256 ? { thumbnail_sha256: a.thumbnail_sha256, thumbnail_media_type: a.thumbnail_media_type } : {}),
+    };
+}
+async function createPost(req, all, auth, body) {
+    const refusal = needScope(auth, ['w_organization_social'], 'posts CREATE on behalf of an organization');
+    if (refusal)
+        return refusal;
+    for (const key of Object.keys(body)) {
+        if (!POST_FIELDS.has(key))
+            return problem(400, 'UNRECOGNIZED_FIELD', `Unrecognized field ${key} on a post`);
+    }
+    for (const key of ['reshareContext', 'container', 'adContext', 'contentLandingPage', 'contentCallToActionLabel']) {
+        if (body[key] !== undefined)
+            return unmodeled(`\`${key}\` on a post`);
+    }
+    // required fields (Posts API error table: "Ensure all required fields such as author, visibility,
+    // distribution, and lifecycleState are present"; Post Schema: commentary is required)
+    if (body.author === undefined)
+        return missingField('author');
+    if (typeof body.author !== 'string')
+        return invalidValue('author', body.author);
+    if (PERSON_URN.test(body.author))
+        return unmodeled('Posting as a member (a person author, w_member_social)');
+    if (!ORG_URN.test(body.author))
+        return invalidUrnType('author', body.author, 'organization or person');
+    if (body.commentary === undefined)
+        return missingField('commentary');
+    if (typeof body.commentary !== 'string')
+        return invalidValue('commentary', body.commentary);
+    if (body.visibility === undefined)
+        return missingField('visibility');
+    if (!VISIBILITIES.has(body.visibility))
+        return invalidValue('visibility', body.visibility);
+    if (body.visibility === 'CONTAINER')
+        return unmodeled('CONTAINER visibility');
+    if (body.distribution === undefined)
+        return missingField('distribution');
+    if (typeof body.distribution !== 'object' || body.distribution === null || Array.isArray(body.distribution))
+        return invalidValue('distribution', body.distribution);
+    const feed = body.distribution.feedDistribution;
+    if (feed === undefined)
+        return missingField('distribution.feedDistribution');
+    if (!FEED_DISTRIBUTIONS.has(feed))
+        return invalidValue('distribution.feedDistribution', feed);
+    const targets = body.distribution.targetEntities;
+    if (targets !== undefined && (!Array.isArray(targets) || targets.length > 0))
+        return unmodeled('Targeted organic posts (distribution.targetEntities)');
+    const channels = body.distribution.thirdPartyDistributionChannels;
+    if (channels !== undefined && (!Array.isArray(channels) || channels.length > 0))
+        return unmodeled('distribution.thirdPartyDistributionChannels');
+    if (body.lifecycleState === undefined)
+        return missingField('lifecycleState');
+    // "PUBLISHED is the only accepted field during creation."
+    if (body.lifecycleState !== 'PUBLISHED')
+        return invalidValue('lifecycleState', body.lifecycleState);
+    if (body.isReshareDisabledByAuthor !== undefined && typeof body.isReshareDisabledByAuthor !== 'boolean')
+        return invalidValue('isReshareDisabledByAuthor', body.isReshareDisabledByAuthor);
+    if (body.lifecycleStateInfo !== undefined || body.publishedAt !== undefined)
+        return problem(400, 'FIELD_NOT_ALLOWED', 'lifecycleStateInfo and publishedAt are read-only');
+    const author = body.author;
+    if (!canPostAs(all, auth, author)) {
+        return accessDenied(`Not enough permissions to post as ${author}: the member holds no ADMINISTRATOR, DIRECT_SPONSORED_CONTENT_POSTER or CONTENT_ADMINISTRATOR role on it`);
+    }
+    // content: at most one kind, and only media or article are modelled.
+    let content;
+    let media;
+    if (body.content !== undefined) {
+        if (typeof body.content !== 'object' || body.content === null || Array.isArray(body.content))
+            return invalidValue('content', body.content);
+        const kinds = Object.keys(body.content);
+        for (const k of kinds)
+            if (!CONTENT_KINDS.has(k))
+                return problem(400, 'UNRECOGNIZED_FIELD', `Unrecognized field content.${k}`);
+        if (kinds.length > 1)
+            return invalidValue('content', kinds.join(','));
+        const kind = kinds[0];
+        if (kind === 'media') {
+            const m = body.content.media;
+            if (typeof m !== 'object' || m === null)
+                return invalidValue('content.media', m);
+            for (const k of Object.keys(m))
+                if (!['id', 'title', 'altText'].includes(k))
+                    return problem(400, 'UNRECOGNIZED_FIELD', `Unrecognized field content.media.${k}`);
+            const resolved = await resolveAsset('content.media.id', m.id, author, true, nowMs(req), req.root);
+            if (isResponse(resolved))
+                return resolved;
+            media = resolved;
+            for (const k of ['title', 'altText'])
+                if (m[k] !== undefined && typeof m[k] !== 'string')
+                    return invalidValue(`content.media.${k}`, m[k]);
+            content = { media: { ...(typeof m.title === 'string' ? { title: m.title } : {}), ...(typeof m.altText === 'string' ? { altText: m.altText } : {}), id: m.id } };
+        }
+        else if (kind === 'article') {
+            const a = body.content.article;
+            if (typeof a !== 'object' || a === null)
+                return invalidValue('content.article', a);
+            if (typeof a.source !== 'string' || a.source === '')
+                return missingField('content.article.source');
+            if (!/^https?:\/\/\S+$/i.test(a.source))
+                return problem(400, 'INVALID_URL', `${a.source} is an invalid URL`);
+            for (const k of Object.keys(a))
+                if (!['source', 'thumbnail', 'thumbnailAltText', 'title', 'description'].includes(k))
+                    return problem(400, 'UNRECOGNIZED_FIELD', `Unrecognized field content.article.${k}`);
+            for (const k of ['title', 'description', 'thumbnailAltText'])
+                if (a[k] !== undefined && typeof a[k] !== 'string')
+                    return invalidValue(`content.article.${k}`, a[k]);
+            if (a.thumbnail !== undefined) {
+                const resolved = await resolveAsset('content.article.thumbnail', a.thumbnail, author, false, nowMs(req), req.root);
+                if (isResponse(resolved))
+                    return resolved;
+                media = resolved;
+            }
+            content = { article: { source: a.source, ...(a.thumbnail !== undefined ? { thumbnail: a.thumbnail } : {}), ...(a.thumbnailAltText !== undefined ? { thumbnailAltText: a.thumbnailAltText } : {}), ...(a.title !== undefined ? { title: a.title } : {}), ...(a.description !== undefined ? { description: a.description } : {}) } };
+        }
+        else if (kind !== undefined) {
+            return unmodeled(`\`content.${kind}\` on a post`);
+        }
+    }
+    const ms = nowMs(req);
+    // The mint and the append are one step under the kernel's lock: two concurrent creates never share a URN.
+    const { value: urn } = await applyTwinWriteAtomic(SERVICE, (resources) => {
+        const minted = mintPostUrn(resources, req.root, `${at(req)}|${author}|${JSON.stringify(body)}`);
+        return {
+            kind: 'write',
+            value: minted,
+            write: {
+                operation: 'linkedin.post.create',
+                subjectType: 'post',
+                subjectId: minted,
+                fields: {
+                    author,
+                    commentary: templateHashtags(body.commentary),
+                    visibility: body.visibility,
+                    distribution: { feedDistribution: feed, thirdPartyDistributionChannels: [] },
+                    ...(content ? { content } : {}),
+                    lifecycleState: 'PUBLISHED',
+                    lifecycleStateInfo: { isEditedByAuthor: false },
+                    isReshareDisabledByAuthor: body.isReshareDisabledByAuthor === true,
+                    createdAt: ms,
+                    publishedAt: ms,
+                    lastModifiedAt: ms,
+                    // The asset by digest: how the mirror's player and a deploy's upload find the bytes, with no
+                    // staged record needed (bookkeeping — never on the wire).
+                    ...(media ? { _media: assetBookkeeping(media) } : {}),
+                    _deleted: false,
+                },
+                occurredAt: at(req),
+                actor: { kind: 'agent', id: auth.member },
+            },
+        };
+    }, req.root);
+    // "You should get a 201 response and the response header x-restli-id contains the Post ID."
+    return { status: 201, body: null, headers: { 'x-restli-id': urn, 'x-restli-protocol-version': '2.0.0' } };
+}
+function readablePost(all, auth, urn, root) {
+    const post = livePost(all, urn, root);
+    if (!post)
+        return notFound(`Post ${urn} not found`);
+    if (!canPostAs(all, auth, String(fields(post).author)))
+        return accessDenied(`Not enough permissions to access: posts GET for ${urn}`);
+    return post;
+}
+function parseViewContext(url) {
+    const view = url.searchParams.get('viewContext');
+    if (view !== null && view !== 'READER' && view !== 'AUTHOR')
+        return invalidValue('viewContext', view);
+    return undefined;
+}
+function getPost(all, auth, rawUrn, url, root) {
+    const refusal = needScope(auth, ['r_organization_social'], 'posts GET');
+    if (refusal)
+        return refusal;
+    const bad = parseViewContext(url);
+    if (bad)
+        return bad;
+    const urn = urnFrom(rawUrn);
+    if (!POST_URN.test(urn))
+        return invalidUrnType('id', urn, 'share or ugcPost');
+    const post = readablePost(all, auth, urn, root);
+    return isResponse(post) ? post : ok(projectPost(post));
+}
+function batchGetPosts(all, auth, ids, root) {
+    const results = {};
+    const statuses = {};
+    const errors = {};
+    for (const urn of ids) {
+        if (!POST_URN.test(urn)) {
+            statuses[urn] = 400;
+            errors[urn] = { status: 400, code: 'INVALID_URN_TYPE', message: `id value ${urn} must be a share or ugcPost URN` };
+            continue;
+        }
+        const post = readablePost(all, auth, urn, root);
+        if (isResponse(post)) {
+            statuses[urn] = post.status;
+            errors[urn] = post.body;
+            continue;
+        }
+        results[urn] = projectPost(post);
+        statuses[urn] = 200;
+    }
+    return ok({ results, statuses, errors });
+}
+function findPostsByAuthor(all, auth, url) {
+    const refusal = needScope(auth, ['r_organization_social'], 'posts FINDER author');
+    if (refusal)
+        return refusal;
+    const author = url.searchParams.get('author');
+    if (author === null)
+        return missingField('author');
+    if (PERSON_URN.test(author))
+        return unmodeled("A member's posts (the author finder over a person URN, r_member_social)");
+    if (!ORG_URN.test(author))
+        return invalidUrnType('author', author, 'organization or person');
+    const bad = parseViewContext(url);
+    if (bad)
+        return bad;
+    const sortBy = url.searchParams.get('sortBy') ?? 'LAST_MODIFIED';
+    if (sortBy !== 'LAST_MODIFIED' && sortBy !== 'CREATED')
+        return invalidValue('sortBy', sortBy);
+    // "The default is 10 and maximum allowed count is 100."
+    const paging = parsePaging(url, 10, 100);
+    if (isResponse(paging))
+        return paging;
+    if (!canPostAs(all, auth, author))
+        return accessDenied(`Not enough permissions to access: posts FINDER author for ${author}`);
+    const key = sortBy === 'CREATED' ? 'createdAt' : 'lastModifiedAt';
+    // descending by the sort key; a tie (one instant) newest-written first: the tree keeps write order
+    const posts = ofType(all, 'post').map((p, i) => ({ p, i })).filter(({ p }) => !isDeleted(p) && fields(p).author === author)
+        .sort((a, b) => (Number(fields(b.p)[key]) - Number(fields(a.p)[key])) || (b.i - a.i)).map(({ p }) => p);
+    return finderPage(posts.map(projectPost), paging, url);
+}
+async function deletePost(req, all, auth, rawUrn) {
+    const refusal = needScope(auth, ['w_organization_social'], 'posts DELETE');
+    if (refusal)
+        return refusal;
+    const urn = urnFrom(rawUrn);
+    if (!POST_URN.test(urn))
+        return invalidUrnType('id', urn, 'share or ugcPost');
+    const post = findPost(all, urn, req.root);
+    if (!post)
+        return notFound(`Post ${urn} not found`);
+    const f = fields(post);
+    if (!canPostAs(all, auth, String(f.author)))
+        return accessDenied(`Not enough permissions to access: posts DELETE for ${urn}`);
+    // "Post deletions are idempotent. Deletion requests for a previously deleted UGC Post will return
+    // a 204" — and write nothing a second time.
+    if (isDeleted(post))
+        return noContent();
+    await applyTwinWrite(SERVICE, {
+        operation: 'linkedin.post.delete',
+        subjectType: 'post',
+        subjectId: String(post.id),
+        fields: { ...f, _deleted: true },
+        occurredAt: at(req),
+        actor: { kind: 'agent', id: auth.member },
+    }, req.root);
+    return noContent();
+}
+// assets: images and videos ───────────────────────────────────────────────────────────────────
+function assetOwnerCheck(all, auth, owner, kind) {
+    if (typeof owner !== 'string' || owner === '')
+        return missingField('initializeUploadRequest.owner');
+    if (PERSON_URN.test(owner))
+        return unmodeled(`A member-owned ${kind} (a person owner)`);
+    if (!ORG_URN.test(owner))
+        return invalidUrnType('initializeUploadRequest.owner', owner, 'organization or person');
+    // "For videos [images] with company URN owners, the caller needs to have ADMIN or DSC permissions."
+    // (Narrower than posting, which CONTENT_ADMINISTRATOR may do: the Videos and Images pages name only these two.)
+    const roles = rolesOn(all, auth.member, owner);
+    if (!roles.has('ADMINISTRATOR') && !roles.has('DIRECT_SPONSORED_CONTENT_POSTER'))
+        return accessDenied(`Accessing this ${kind} resource is forbidden. Please check your permissions for this resource`);
+    return undefined;
+}
+const uploadBase = (req) => (req.publicBase ?? UPLOAD_HOST).replace(/\/+$/, '');
+async function uploadUrl(req, asset, slot) {
+    const ut = await signUpload(asset, slot, asset.upload_expires_ms);
+    return `${uploadBase(req)}/dms-uploads/${asset.id}/${slot}?ca=vector_ads&cn=uploads&sync=0&v=beta&e=${asset.upload_expires_ms}&ut=${ut}`;
+}
+async function initializeImageUpload(req, all, auth, body) {
+    const refusal = needScope(auth, ['w_organization_social', 'rw_ads', 'w_member_social'], 'images initializeUpload');
+    if (refusal)
+        return refusal;
+    const init = body.initializeUploadRequest;
+    if (typeof init !== 'object' || init === null)
+        return missingField('initializeUploadRequest');
+    if (init.mediaLibraryMetadata !== undefined)
+        return unmodeled('The media library (initializeUploadRequest.mediaLibraryMetadata)');
+    const denied = assetOwnerCheck(all, auth, init.owner, 'image');
+    if (denied)
+        return denied;
+    const id = await mintAssetId(req.root);
+    const created = nowMs(req);
+    const expires = created + UPLOAD_URL_LIFETIME_MS;
+    const asset = { kind: 'image', id, owner: init.owner, status: 'WAITING_UPLOAD', created_ms: created, upload_expires_ms: expires, upload_secret: newUploadSecret() };
+    await writeAsset(asset, req.root);
+    return ok({ value: { uploadUrlExpiresAt: expires, uploadUrl: await uploadUrl(req, asset, 'uploaded-image/0'), image: `urn:li:image:${id}` } });
+}
+async function initializeVideoUpload(req, all, auth, body) {
+    const refusal = needScope(auth, ['w_organization_social', 'rw_ads', 'w_member_social'], 'videos initializeUpload');
+    if (refusal)
+        return refusal;
+    const init = body.initializeUploadRequest;
+    if (typeof init !== 'object' || init === null)
+        return missingField('initializeUploadRequest');
+    for (const k of ['mediaLibraryMetadata', 'templateName', 'linkbackContext']) {
+        if (init[k] !== undefined)
+            return unmodeled(`initializeUploadRequest.${k}`);
+    }
+    if (init.uploadCaptions === true)
+        return unmodeled('Caption upload (initializeUploadRequest.uploadCaptions)');
+    const denied = assetOwnerCheck(all, auth, init.owner, 'video');
+    if (denied)
+        return denied;
+    const size = init.fileSizeBytes;
+    if (size === undefined)
+        return missingField('initializeUploadRequest.fileSizeBytes');
+    if (typeof size !== 'number' || !Number.isInteger(size) || size <= 0)
+        return invalidValue('initializeUploadRequest.fileSizeBytes', size);
+    // "Maximum allowed Videos size is 5GB." (the feed ceiling of 500MB is checked on the bytes)
+    if (size > 5 * 1024 ** 3)
+        return problem(400, 'FIELD_VALUE_TOO_HIGH', `initializeUploadRequest.fileSizeBytes value ${size} can't be higher than ${5 * 1024 ** 3}`);
+    // A feed video is at most 500 MB; the larger (ads) videos LinkedIn takes are surface this twin does
+    // not model — and a finalize assembles the file in memory, so it is refused before any byte arrives.
+    if (size > MAX_VIDEO_BYTES)
+        return unmodeled(`A video over the feed's 500 MB (${size} bytes; the ads videos up to 5 GB)`);
+    for (const k of ['uploadCaptions', 'uploadThumbnail'])
+        if (init[k] !== undefined && typeof init[k] !== 'boolean')
+            return invalidValue(`initializeUploadRequest.${k}`, init[k]);
+    const id = await mintAssetId(req.root);
+    const created = nowMs(req);
+    const expires = created + UPLOAD_URL_LIFETIME_MS;
+    const parts = [];
+    for (let first = 0; first < size; first += VIDEO_PART_BYTES)
+        parts.push({ firstByte: first, lastByte: Math.min(size, first + VIDEO_PART_BYTES) - 1 });
+    const thumbnail = init.uploadThumbnail === true;
+    const asset = {
+        kind: 'video', id, owner: init.owner, status: 'WAITING_UPLOAD', created_ms: created, upload_expires_ms: expires,
+        file_size_bytes: size, parts, upload_thumbnail: thumbnail, upload_captions: false, upload_secret: newUploadSecret(),
+    };
+    await writeAsset(asset, req.root);
+    const instructions = [];
+    for (let i = 0; i < parts.length; i += 1) {
+        instructions.push({ uploadUrl: await uploadUrl(req, asset, `uploadedVideo/${i}`), lastByte: parts[i].lastByte, firstByte: parts[i].firstByte });
+    }
+    return ok({
+        value: {
+            uploadUrlsExpireAt: expires,
+            video: `urn:li:video:${id}`,
+            uploadInstructions: instructions,
+            // The docs' samples answer an empty token for these uploads; the twin does the same, and
+            // finalize accepts exactly what initialize answered.
+            uploadToken: '',
+            ...(thumbnail ? { thumbnailUploadUrl: await uploadUrl(req, asset, 'ads-video-userUploadedThumbnail/0') } : {}),
+        },
+    });
+}
+async function finalizeVideoUpload(req, all, auth, body) {
+    const refusal = needScope(auth, ['w_organization_social', 'rw_ads', 'w_member_social'], 'videos finalizeUpload');
+    if (refusal)
+        return refusal;
+    const fin = body.finalizeUploadRequest;
+    if (typeof fin !== 'object' || fin === null)
+        return missingField('finalizeUploadRequest');
+    const m = typeof fin.video === 'string' ? VIDEO_URN.exec(fin.video) : null;
+    if (!m)
+        return fin.video === undefined ? missingField('finalizeUploadRequest.video') : invalidUrnType('finalizeUploadRequest.video', fin.video, 'video');
+    // in the asset's chain: no part PUT can land between reading the parts and writing PROCESSING
+    return withAsset(m[1], req.root, () => finalizeLocked(req, all, auth, fin, m[1]));
+}
+async function finalizeLocked(req, all, auth, fin, videoId) {
+    const asset = await readAsset(videoId, req.root);
+    if (!asset || asset.kind !== 'video')
+        return problem(400, 'INVALID_VIDEO_ID', 'This Video ID is invalid');
+    if (!(await assetIsOwn(videoId, req.root)))
+        return anotherWorldsUpload(videoId);
+    const denied = assetOwnerCheck(all, auth, asset.owner, 'video');
+    if (denied)
+        return denied;
+    if (asset.status !== 'WAITING_UPLOAD')
+        return invalidValue('finalizeUploadRequest.video', `${fin.video} (already ${asset.status})`);
+    if (fin.uploadToken !== undefined && fin.uploadToken !== '')
+        return invalidValue('finalizeUploadRequest.uploadToken', fin.uploadToken);
+    const ids = fin.uploadedPartIds;
+    const parts = asset.parts ?? [];
+    // "The order needs to be the same as the order of parts in the upload instructions."
+    if (!Array.isArray(ids) || ids.length !== parts.length)
+        return invalidValue('finalizeUploadRequest.uploadedPartIds', `${Array.isArray(ids) ? ids.length : 0} ids for ${parts.length} parts`);
+    for (let i = 0; i < parts.length; i += 1) {
+        if (!parts[i].etag || ids[i] !== parts[i].etag)
+            return invalidValue(`finalizeUploadRequest.uploadedPartIds[${i}]`, ids[i]);
+    }
+    if (asset.upload_thumbnail && !asset.thumbnail_sha256)
+        return problem(400, 'MEDIA_ASSET_WAITING_UPLOAD', 'Media asset is waiting upload (the thumbnail requested at initialize was never uploaded)');
+    const chunks = [];
+    for (let i = 0; i < parts.length; i += 1) {
+        const bytes = await readPart(asset.id, i, req.root);
+        if (!bytes)
+            return invalidValue(`finalizeUploadRequest.uploadedPartIds[${i}]`, ids[i]);
+        chunks.push(bytes);
+    }
+    const whole = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+    let offset = 0;
+    for (const c of chunks) {
+        whole.set(c, offset);
+        offset += c.length;
+    }
+    const stored = await putLinkedinBlob(whole, req.root);
+    await clearParts(asset.id, req.root);
+    // Processing, as LinkedIn does it after finalize: a file that is not an MP4 with a video track, or
+    // outside the feed's size and length bounds, FAILS processing rather than refusing the finalize.
+    const info = sniffVideo(whole);
+    let failure;
+    if (!info)
+        failure = 'The file is not an MP4 with a video track.';
+    else if (whole.length < MIN_VIDEO_BYTES || whole.length > MAX_VIDEO_BYTES)
+        failure = `File size ${whole.length} is outside 75KB to 500MB.`;
+    else if (info.durationMs < MIN_VIDEO_MS || info.durationMs > MAX_VIDEO_MS)
+        failure = `Length ${info.durationMs}ms is outside three seconds to 30 minutes.`;
+    await writeAsset({
+        ...asset, sha256: stored.sha256, size: whole.length, media_type: 'video/mp4',
+        ...(info ? { width: info.width, height: info.height, duration_ms: info.durationMs } : {}),
+        ...(failure ? { status: 'PROCESSING_FAILED', processing_failure_reason: failure } : { status: 'PROCESSING', finalized_ms: nowMs(req) }),
+    }, req.root);
+    // "A successful response returns the 200 OK status code." — with no body in the docs' sample.
+    return { status: 200, body: null, headers: { 'x-restli-protocol-version': '2.0.0' } };
+}
+/** An upload started in an ancestor World (a clone's origin, a branch's parent): finished there, never here. */
+const anotherWorldsUpload = (id) => problem(409, 'CONFLICT', `This upload (${id}) was started in another World; finish it there`);
+const downloadBase = (req, host) => (req.publicBase ?? host).replace(/\/+$/, '');
+/** An asset as the Images / Videos API answers it. */
+function projectAsset(req, asset) {
+    const out = { owner: asset.owner, id: `urn:li:${asset.kind}:${asset.id}`, status: asset.status };
+    const available = asset.status === 'AVAILABLE';
+    if (available && asset.sha256) {
+        const expires = asset.created_ms + UPLOAD_URL_LIFETIME_MS;
+        if (asset.kind === 'image') {
+            out.downloadUrl = `${downloadBase(req, IMAGE_HOST)}/dms/image/${asset.id}/image-shrink_1280/0/${asset.sha256}?e=${expires}`;
+        }
+        else {
+            out.downloadUrl = `${downloadBase(req, VIDEO_HOST)}/playlist/${asset.id}/mp4-${Math.min(asset.width ?? 720, asset.height ?? 720)}p-30fp-crf28/0/${asset.sha256}?e=${expires}`;
+            out.thumbnail = asset.thumbnail_sha256
+                ? `${downloadBase(req, IMAGE_HOST)}/dms/image/${asset.id}/ads-video-thumbnail_720_1280/0/${asset.thumbnail_sha256}?e=${expires}`
+                : `${downloadBase(req, IMAGE_HOST)}/dms/image/${asset.id}/ads-video-thumbnail_720_1280/0/system?e=${expires}`;
+            if (asset.duration_ms !== undefined)
+                out.duration = asset.duration_ms;
+        }
+        out.downloadUrlExpiresAt = expires;
+        if (asset.width && asset.height) {
+            const r = aspectRatio(asset.width, asset.height);
+            out.aspectRatioWidth = r.w;
+            out.aspectRatioHeight = r.h;
+        }
+    }
+    if (asset.status === 'PROCESSING_FAILED' && asset.processing_failure_reason)
+        out.processingFailureReason = asset.processing_failure_reason;
+    return out;
+}
+async function getAsset(req, all, auth, kind, rawUrn) {
+    // "tokens with only w_member_social permissions would be unable to perform a GET call for rest/images"
+    const refusal = needScope(auth, ['w_organization_social', 'r_organization_social', 'rw_ads', 'r_ads'], `${kind}s GET`);
+    if (refusal)
+        return refusal;
+    const urn = urnFrom(rawUrn);
+    const m = (kind === 'image' ? IMAGE_URN : VIDEO_URN).exec(urn);
+    if (!m)
+        return invalidUrnType('id', urn, kind);
+    const asset = await readAsset(m[1], req.root);
+    if (!asset || asset.kind !== kind)
+        return notFound('Could not find entity');
+    if (!canPostAs(all, auth, asset.owner))
+        return accessDenied(`Accessing this ${kind} resource is forbidden. Please check your permissions for this resource`);
+    // PROCESSING -> AVAILABLE is a fold of the stored finalize instant and this request's world instant
+    // (PROCESSING_MS later), so a client that polls as LinkedIn asks reaches it, one that posts at once is
+    // refused, and READING NEVER MOVES ANYTHING — a preview in the mirror changes no state.
+    return ok(projectAsset(req, assetAsOf(asset, nowMs(req))));
+}
+/** A PUT to a signed upload URL: an image, a video part, or a video's thumbnail. A video part or
+ *  thumbnail carries no bearer — the URL's own signature is its authorization (the Videos API's
+ *  upload samples send none). An IMAGE upload also needs the member's access token in
+ *  Authorization, as LinkedIn's image upload does ("Upload the Image" in the Assets / Images docs). */
+async function receiveUpload(req, url) {
+    const m = /^\/dms-uploads\/([A-Za-z0-9_-]{8,40})\/(uploaded-image\/0|uploadedVideo\/(\d{1,4})|ads-video-userUploadedThumbnail\/0)$/.exec(url.pathname);
+    if (!m || !isAssetId(m[1]))
+        return notFound();
+    // in the asset's chain: concurrent part PUTs each read the record the previous one wrote
+    return withAsset(m[1], req.root, () => receiveUploadLocked(req, url, m));
+}
+async function receiveUploadLocked(req, url, m) {
+    const [, id, slot, partIndex] = m;
+    const ut = url.searchParams.get('ut') ?? '';
+    const expires = Number(url.searchParams.get('e'));
+    const asset = await readAsset(id, req.root);
+    if (asset && !hasUploadSecret(asset)) {
+        return problem(400, 'INVALID_UPLOAD_URL', `The upload of ${id} was started before its upload URLs were signed per asset; initialize a new upload`);
+    }
+    if (!asset || !Number.isFinite(expires) || expires !== asset.upload_expires_ms || !(await verifyUpload(asset, slot, expires, ut))) {
+        return problem(401, 'INVALID_UPLOAD_SIGNATURE', 'The upload URL signature is invalid');
+    }
+    if (nowMs(req) > expires)
+        return problem(400, 'EXPIRED_UPLOAD_URL', 'The Video upload URL is expired');
+    // A branch writes only the assets it started: an inherited record (and its parts) stays the ancestor's,
+    // so a clone never holds a stale copy of the origin's asset and its push can never roll the origin back.
+    if (!(await assetIsOwn(id, req.root)))
+        return anotherWorldsUpload(id);
+    if (asset.status !== 'WAITING_UPLOAD')
+        return problem(400, 'UPLOAD_ALREADY_COMPLETE', `Asset ${id} is ${asset.status}; its upload is complete`);
+    const bytes = req.bytes ?? new Uint8Array();
+    if (bytes.length === 0)
+        return missingField('request body');
+    if (slot === 'uploaded-image/0') {
+        if (asset.kind !== 'image')
+            return notFound();
+        const all = resources(req.root);
+        const auth = authorize(all, req.headers);
+        if (isResponse(auth))
+            return auth;
+        const scope = needScope(auth, ['w_organization_social', 'rw_ads', 'w_member_social'], 'an image upload');
+        if (scope)
+            return scope;
+        const denied = assetOwnerCheck(all, auth, asset.owner, 'image');
+        if (denied)
+            return denied;
+        const info = sniffImage(bytes);
+        if (!info) {
+            await writeAsset({ ...asset, status: 'PROCESSING_FAILED', processing_failure_reason: 'Unsupported image format: the Images API takes JPG, GIF and PNG.' }, req.root);
+            return { status: 201, body: null, headers: {} };
+        }
+        const stored = await putLinkedinBlob(bytes, req.root);
+        const tooBig = info.width * info.height >= MAX_IMAGE_PIXELS;
+        await writeAsset({
+            ...asset, sha256: stored.sha256, size: bytes.length, media_type: info.mediaType, width: info.width, height: info.height,
+            ...(tooBig ? { status: 'PROCESSING_FAILED', processing_failure_reason: `The image has ${info.width * info.height} pixels; the limit is under ${MAX_IMAGE_PIXELS}.` } : { status: 'AVAILABLE' }),
+        }, req.root);
+        return { status: 201, body: null, headers: {} };
+    }
+    if (asset.kind !== 'video')
+        return notFound();
+    if (slot === 'ads-video-userUploadedThumbnail/0') {
+        if (!asset.upload_thumbnail)
+            return notFound();
+        const info = sniffImage(bytes);
+        if (!info)
+            return problem(400, 'INVALID_IMAGE', 'The thumbnail is not a JPG, GIF or PNG image');
+        const stored = await putLinkedinBlob(bytes, req.root);
+        await writeAsset({ ...asset, thumbnail_sha256: stored.sha256, thumbnail_media_type: info.mediaType }, req.root);
+        return { status: 201, body: null, headers: {} };
+    }
+    const index = Number(partIndex);
+    const part = asset.parts?.[index];
+    if (!part)
+        return notFound();
+    const expected = part.lastByte - part.firstByte + 1;
+    if (bytes.length !== expected)
+        return invalidValue('part', `${bytes.length} bytes for the byte range ${part.firstByte}-${part.lastByte} (${expected} bytes)`);
+    await putPart(asset.id, index, bytes, req.root);
+    // The ETag names what was stored: a digest of the part, in the vendor's opaque signedId form.
+    const digest = blobDigest(bytes);
+    const etag = `/ambry-video/signedId/${digest}.bin`;
+    const partsNext = [...(asset.parts ?? [])];
+    partsNext[index] = { ...part, etag, sha256: digest };
+    await writeAsset({ ...asset, parts: partsNext }, req.root);
+    return { status: 200, body: null, headers: { etag } };
+}
+// ── /v2/userinfo (OpenID Connect) ─────────────────────────────────────────────────────────────
+function userinfo(all, auth) {
+    if (!auth.scopes.has('openid'))
+        return accessDenied('Not enough permissions to access: userinfo (the openid scope is required)');
+    const id = PERSON_URN.exec(auth.member)?.[1] ?? '';
+    const member = ofType(all, 'member').find((m) => String(m.id) === id);
+    if (!member)
+        return notFound('Member not found');
+    const f = fields(member);
+    const given = String(f.localizedFirstName ?? '');
+    const family = String(f.localizedLastName ?? '');
+    return ok({
+        sub: id,
+        ...(auth.scopes.has('profile') ? { name: `${given} ${family}`.trim(), given_name: given, family_name: family, locale: 'en-US' } : {}),
+        ...(auth.scopes.has('email') && typeof f.email === 'string' ? { email: f.email, email_verified: true } : {}),
+    });
+}
+// ── the twin control plane ───────────────────────────────────────────────────────────────────
+// Not vendor surface. `/_twin/*` is how a WORLD seeds what LinkedIn's own UI and OAuth leg would
+// have made: the company page, the member, the admin role that member holds on it, and the access
+// token the 3-legged OAuth flow would have minted.
+async function handleTwinControl(req, all, path, body) {
+    if (req.method !== 'POST')
+        return notFound();
+    if (path === '/_twin/organizations') {
+        const id = String(body.id ?? '');
+        if (!/^\d{1,19}$/.test(id))
+            return invalidValue('id', body.id);
+        if (typeof body.localizedName !== 'string' || body.localizedName.trim() === '')
+            return missingField('localizedName');
+        const vanityName = typeof body.vanityName === 'string' ? body.vanityName : body.localizedName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+        if (!/^[A-Za-z0-9-]{1,100}$/.test(vanityName))
+            return invalidValue('vanityName', vanityName);
+        if (ofType(all, 'organization').some((o) => String(o.id) !== id && String(fields(o).vanityName).toLowerCase() === vanityName.toLowerCase())) {
+            return invalidValue('vanityName', `${vanityName} (already another page's)`);
+        }
+        for (const k of ['localizedWebsite', 'localizedDescription'])
+            if (body[k] !== undefined && typeof body[k] !== 'string')
+                return invalidValue(k, body[k]);
+        if (body.followerCount !== undefined && (!Number.isInteger(body.followerCount) || body.followerCount < 0))
+            return invalidValue('followerCount', body.followerCount);
+        if (body.industries !== undefined && (!Array.isArray(body.industries) || body.industries.some((i) => typeof i !== 'string')))
+            return invalidValue('industries', body.industries);
+        // The logo is an image this org uploaded through the Images API, named by URN as logoV2 names it.
+        if (body.logo !== undefined) {
+            const m = typeof body.logo === 'string' ? IMAGE_URN.exec(body.logo) : null;
+            const asset = m ? await readAsset(m[1], req.root) : undefined;
+            if (!asset || asset.status !== 'AVAILABLE' || asset.owner !== `urn:li:organization:${id}`)
+                return invalidValue('logo', `${String(body.logo)} (an AVAILABLE image owned by urn:li:organization:${id})`);
+        }
+        const f = {
+            localizedName: body.localizedName, vanityName,
+            ...(body.localizedWebsite !== undefined ? { localizedWebsite: body.localizedWebsite } : {}),
+            ...(body.localizedDescription !== undefined ? { localizedDescription: body.localizedDescription } : {}),
+            ...(body.industries !== undefined ? { industries: body.industries } : {}),
+            ...(body.logo !== undefined ? { logo: body.logo } : {}),
+            followerCount: body.followerCount ?? 0,
+        };
+        await applyTwinWrite(SERVICE, { operation: 'linkedin.twin.seed_organization', subjectType: 'organization', subjectId: id, fields: f, occurredAt: at(req) }, req.root);
+        return ok({ id: Number(id), $URN: `urn:li:organization:${id}`, ...f });
+    }
+    if (path === '/_twin/members') {
+        const id = String(body.id ?? '');
+        if (!/^[A-Za-z0-9_-]{1,40}$/.test(id))
+            return invalidValue('id', body.id);
+        if (typeof body.localizedFirstName !== 'string' || body.localizedFirstName === '')
+            return missingField('localizedFirstName');
+        if (typeof body.localizedLastName !== 'string')
+            return missingField('localizedLastName');
+        if (typeof body.email !== 'string' || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(body.email))
+            return invalidValue('email', body.email);
+        if (ofType(all, 'member').some((m) => String(m.id) !== id && String(fields(m).email).toLowerCase() === body.email.toLowerCase()))
+            return invalidValue('email', `${body.email} (already another member's)`);
+        const f = { localizedFirstName: body.localizedFirstName, localizedLastName: body.localizedLastName, email: body.email };
+        await applyTwinWrite(SERVICE, { operation: 'linkedin.twin.seed_member', subjectType: 'member', subjectId: id, fields: f, occurredAt: at(req) }, req.root);
+        return ok({ id, $URN: `urn:li:person:${id}`, ...f });
+    }
+    if (path === '/_twin/organizationAcls') {
+        const { organization, roleAssignee, role } = body;
+        const state = body.state ?? 'APPROVED';
+        if (typeof organization !== 'string' || !ORG_URN.test(organization) || !findOrg(all, String(orgNumber(organization))))
+            return invalidValue('organization', `${String(organization)} (a seeded organization URN)`);
+        const person = typeof roleAssignee === 'string' ? PERSON_URN.exec(roleAssignee) : null;
+        if (!person || !ofType(all, 'member').some((m) => String(m.id) === person[1]))
+            return invalidValue('roleAssignee', `${String(roleAssignee)} (a seeded person URN)`);
+        if (!ROLES.has(role))
+            return invalidValue('role', role);
+        if (!ROLE_STATES.has(state))
+            return invalidValue('state', state);
+        const f = { organization, roleAssignee, role, state };
+        await applyTwinWrite(SERVICE, { operation: 'linkedin.twin.seed_acl', subjectType: 'organization_acl', subjectId: `${organization}|${role}|${roleAssignee}`, fields: f, occurredAt: at(req) }, req.root);
+        return ok(f);
+    }
+    if (path === '/_twin/tokens') {
+        const token = body.token;
+        if (typeof token !== 'string' || !/^[A-Za-z0-9._~-]{8,512}$/.test(token))
+            return invalidValue('token', '(8-512 characters of A-Z a-z 0-9 . _ ~ -)');
+        const person = typeof body.member === 'string' ? PERSON_URN.exec(body.member) : null;
+        if (!person || !ofType(all, 'member').some((m) => String(m.id) === person[1]))
+            return invalidValue('member', `${String(body.member)} (a seeded person URN)`);
+        const scopes = Array.isArray(body.scopes) ? body.scopes.map(String) : String(body.scopes ?? '').split(/[\s,]+/).filter((s) => s !== '');
+        for (const s of scopes)
+            if (!SCOPES_DOCUMENTED.has(s))
+                return invalidValue('scopes', s);
+        await applyTwinWrite(SERVICE, { operation: 'linkedin.twin.seed_token', subjectType: 'token', subjectId: token, fields: { member: body.member, scopes }, occurredAt: at(req) }, req.root);
+        return ok({ member: body.member, scopes });
+    }
+    return notFound();
+}
+// ── the router ───────────────────────────────────────────────────────────────────────────────
+const POST_BY_URN = /^\/rest\/posts\/([^/]+)$/;
+const IMAGE_BY_URN = /^\/rest\/images\/([^/]+)$/;
+const VIDEO_BY_URN = /^\/rest\/videos\/([^/]+)$/;
+const ORG_BY_ID = /^\/rest\/organizations\/([^/]+)$/;
+const NETWORK_SIZE = /^\/rest\/networkSizes\/([^/]+)$/;
+export async function handleLinkedinTwinRequest(req) {
+    const url = new URL(req.path, 'http://twin.local');
+    const path = url.pathname.replace(/\/+$/, '') || '/';
+    const method = req.method.toUpperCase();
+    // The signed upload URLs: a PUT of bytes, authorized by the URL's own signature.
+    if (path.startsWith('/dms-uploads/')) {
+        if (method !== 'PUT')
+            return notFound();
+        if (req.readOnly)
+            return readOnlyRefusal();
+        return receiveUpload(req, url);
+    }
+    const parsed = parseJson(req.body);
+    if ('malformed' in parsed)
+        return problem(400, 'INVALID_JSON', 'The request body could not be parsed as a JSON object');
+    const body = parsed.object;
+    const all = resources(req.root);
+    if (path.startsWith('/_twin/')) {
+        if (req.readOnly)
+            return readOnlyRefusal();
+        return handleTwinControl(req, all, path, body);
+    }
+    if (path === '/v2/userinfo' && method === 'GET') {
+        const auth = authorize(all, req.headers);
+        return isResponse(auth) ? auth : userinfo(all, auth);
+    }
+    // Everything else of LinkedIn's is under /rest; anything outside it is the vendor's not-found.
+    if (!path.startsWith('/rest/'))
+        return notFound();
+    const version = versionGate(req.headers);
+    if (version)
+        return version;
+    const auth = authorize(all, req.headers);
+    if (isResponse(auth))
+        return auth;
+    // Rest.li names some methods in a header: PARTIAL_UPDATE of a post rides POST /rest/posts/{urn}.
+    const restliMethod = (header(req.headers, 'x-restli-method') ?? '').toUpperCase();
+    const write = method !== 'GET' && method !== 'HEAD';
+    if (write && req.readOnly)
+        return readOnlyRefusal();
+    if (path === '/rest/posts') {
+        if (method === 'POST')
+            return createPost(req, all, auth, body);
+        if (method === 'GET') {
+            const ids = restliList(url.searchParams.get('ids'));
+            if (ids !== undefined) {
+                const refusal = needScope(auth, ['r_organization_social'], 'posts BATCH_GET');
+                return refusal ?? batchGetPosts(all, auth, ids, req.root);
+            }
+            const q = url.searchParams.get('q');
+            if (q === 'author')
+                return findPostsByAuthor(all, auth, url);
+            if (q === 'dscAdAccount')
+                return unmodeled('The dscAdAccount finder on /rest/posts');
+            return q === null ? missingField('q') : invalidValue('q', q);
+        }
+    }
+    const postByUrn = POST_BY_URN.exec(path);
+    if (postByUrn) {
+        if (method === 'GET')
+            return getPost(all, auth, postByUrn[1], url, req.root);
+        if (method === 'DELETE')
+            return deletePost(req, all, auth, postByUrn[1]);
+        if (method === 'POST' && restliMethod === 'PARTIAL_UPDATE')
+            return unmodeled('Updating a post (PARTIAL_UPDATE)');
+        if (method === 'POST')
+            return unmodeled('Query tunneling on /rest/posts/{urn}');
+    }
+    if (path === '/rest/images' && method === 'POST') {
+        const action = url.searchParams.get('action');
+        if (action === 'initializeUpload')
+            return initializeImageUpload(req, all, auth, body);
+        return action === null ? missingField('action') : invalidValue('action', action);
+    }
+    if (path === '/rest/videos' && method === 'POST') {
+        const action = url.searchParams.get('action');
+        if (action === 'initializeUpload')
+            return initializeVideoUpload(req, all, auth, body);
+        if (action === 'finalizeUpload')
+            return finalizeVideoUpload(req, all, auth, body);
+        return action === null ? missingField('action') : invalidValue('action', action);
+    }
+    if ((path === '/rest/images' || path === '/rest/videos') && method === 'GET') {
+        return unmodeled(url.searchParams.get('ids') !== null ? `Batch get of ${path}` : `The associatedAccount finder on ${path}`);
+    }
+    const imageByUrn = IMAGE_BY_URN.exec(path);
+    if (imageByUrn && method === 'GET')
+        return getAsset(req, all, auth, 'image', imageByUrn[1]);
+    if (imageByUrn && method === 'POST')
+        return unmodeled('Updating an image (media library metadata)');
+    const videoByUrn = VIDEO_BY_URN.exec(path);
+    if (videoByUrn && method === 'GET')
+        return getAsset(req, all, auth, 'video', videoByUrn[1]);
+    if (videoByUrn && method === 'POST')
+        return unmodeled('Updating a video (media library metadata)');
+    if (path === '/rest/organizationAcls' && method === 'GET')
+        return findAcls(all, auth, url);
+    if (path.startsWith('/rest/organizationAcls/') && method === 'PUT')
+        return unmodeled('Requesting a role (PUT /rest/organizationAcls)');
+    if (path === '/rest/organizations' && method === 'GET')
+        return findOrganizations(all, url);
+    if (path === '/rest/organizationsLookup' && method === 'GET')
+        return lookupOrganizations(all, url);
+    const orgById = ORG_BY_ID.exec(path);
+    if (orgById && method === 'GET')
+        return getOrganization(all, auth, urnFrom(orgById[1]));
+    const size = NETWORK_SIZE.exec(path);
+    if (size && method === 'GET')
+        return networkSize(all, size[1], url);
+    return notFound();
+}