@oxy.so/federation 1.0.0

package/dist/esm/actorObject.js

@@ -0,0 +1,210 @@
+/**
+ * The single builder of a LOCAL user's ActivityPub actor document.
+ *
+ * Shared by the GET actor route (which serves it as a standalone JSON-LD
+ * document) and the outbound `Update` broadcast (which embeds it in an
+ * `Update` activity), so a follower's Mastodon renders the same actor whether it
+ * was fetched or pushed. Deliberately does NOT include the top-level `@context`:
+ * the GET route and the `Update` envelope each own their JSON-LD context, and an
+ * embedded actor object must not double-declare it.
+ *
+ * The exact bytes of this document are load-bearing — Mastodon negative-caches a
+ * malformed actor — so the field set, ordering, and the absolute-URL invariant on
+ * `icon`/`image` must stay byte-identical across every app that uses the engine.
+ *
+ * Media resolution is injected ({@link ActorMediaResolver}): the engine holds no
+ * knowledge of any app's media pipeline. The app resolves an avatar/banner
+ * reference (Oxy file id or URL) to a final absolute URL; the engine enforces the
+ * absolute-URL invariant and assembles the AP `Image` object.
+ */
+import { isAccountKind } from '@oxy.so/contracts';
+/**
+ * The five actor types AS2 defines — the vocabulary for RECOGNIZING any actor,
+ * local or remote, as opposed to {@link LocalActorType} (the subset we emit).
+ *
+ * An inbound `Update` carrying a profile is dispatched on this: gating it on a
+ * hand-written subset is how a receiver silently stops applying profile edits
+ * from a whole class of account (a Lemmy community is a `Group`), with no error
+ * anywhere — the edit simply never lands.
+ */
+export const AP_ACTOR_TYPES = [
+    'Application',
+    'Group',
+    'Organization',
+    'Person',
+    'Service',
+];
+/** Whether an untrusted inbound `type` names an AS2 actor. */
+export function isApActorType(value) {
+    return typeof value === 'string' && AP_ACTOR_TYPES.includes(value);
+}
+/**
+ * Oxy account kind → the AS2 actor type the fediverse is told about it.
+ *
+ * `satisfies Record<AccountKind, LocalActorType>` is the load-bearing part: a
+ * kind added to `@oxy.so/contracts` fails THIS build rather than silently
+ * inheriting `Person`, which is how every non-person account came to describe
+ * itself as an individual human in the first place.
+ *
+ * Per kind, and why:
+ *
+ *  - **`personal` → `Person`.** The only kind that is a human login. Unchanged.
+ *  - **`organization` → `Organization`.** AS2 has the exact word.
+ *  - **`project` → `Organization`.** Least-wrong of the three available: a
+ *    project is a collective endeavour, not an individual (`Person`) and not an
+ *    automated one (`Service`).
+ *  - **`bot` → `Service`.** Not merely AS2's word for automation — it is
+ *    literally the value Mastodon writes when a local user ticks "this is an
+ *    automated account" (`account.rb:224`), so it is the same claim its own
+ *    users make about themselves. An Oxy `bot` announcing itself as a `Person`
+ *    is false, and readers specifically want it labelled.
+ *  - **`channel` → `Organization`.** A channel is a CONTENT identity that can
+ *    never be logged into and takes no replies, so `Person` is false about it.
+ *    `Group` would promise forwarding (above). `Service` was the tempting answer
+ *    and is the WRONG one: it is the automation claim, and a channel is curated
+ *    by people. Mastodon's `bot?` is exactly `%w(Application Service)`
+ *    (`account.rb:90`), which paints an **"Automated"** badge with a robot icon
+ *    (`badges.tsx:69`), drops the account from `SimilarProfilesSource`
+ *    (`similar_profiles_source.rb:22-36`), and makes its notifications
+ *    discardable by policy; Lemmy sets `bot_account = true`, hiding it from
+ *    anyone who turned bots off. `Organization` costs NOTHING measurable: it is
+ *    accepted by all four implementations' whitelists and compared in none of
+ *    them — neither `bot?` nor `group?` in Mastodon, `bot_account = false` in
+ *    Lemmy, `isBot` false in Misskey, an ordinary account in PeerTube.
+ *
+ * What this does NOT do: it does not stop a remote instance offering a reply box
+ * under a channel's post. NO actor type gates that in any of the four — Mastodon
+ * has no `canReply` at all (only `canQuote` and `canFeature`) — and AS2 has no
+ * interaction-policy field deployed software honours. A reply to a channel is
+ * still accepted by the sender's own instance and still dropped on arrival here.
+ * This map only stops asserting personhood about things that are not people.
+ */
+export const LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND = {
+    personal: 'Person',
+    organization: 'Organization',
+    project: 'Organization',
+    bot: 'Service',
+    channel: 'Organization',
+};
+/**
+ * The AS2 actor type for an Oxy account kind, defaulting to `Person`.
+ *
+ * Takes `unknown` rather than `AccountKind` on purpose: the value arrives in an
+ * Oxy API response, so the static type is a claim about the wire that the wire
+ * can break. A deployment whose API knows a kind this package does not would
+ * index a miss and emit `type: undefined` — a MALFORMED actor, which Mastodon
+ * negative-caches for minutes to hours. `isAccountKind` (contracts' own narrowing,
+ * so it cannot drift from the vocabulary) sends an unrecognized or absent kind to
+ * `Person`: a valid actor, and the value every actor carried before this map
+ * existed.
+ */
+export function localActorTypeForAccountKind(kind) {
+    return isAccountKind(kind) ? LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND[kind] : 'Person';
+}
+/** Map common image extensions to a MIME type for an actor image `mediaType`. */
+const IMAGE_MEDIA_TYPE_BY_EXT = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    avif: 'image/avif',
+};
+/** True when `value` is an absolute `http(s)` URL. */
+function isAbsoluteHttpUrl(value) {
+    try {
+        return /^https?:$/i.test(new URL(value).protocol);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build an ActivityPub `Image` object from an already-absolute URL, deriving
+ * `mediaType` from the URL extension when recognizable (a bare `Image` with a
+ * `url` is spec-valid, so an unknown extension simply omits `mediaType` rather
+ * than asserting a wrong one). Shared by the actor `icon` (avatar) and `image`
+ * (profile banner) builders.
+ */
+function apImageObject(url) {
+    let extension;
+    try {
+        extension = new URL(url).pathname.split('.').pop()?.toLowerCase();
+    }
+    catch {
+        extension = url.split('?')[0]?.split('.').pop()?.toLowerCase();
+    }
+    const mediaType = extension ? IMAGE_MEDIA_TYPE_BY_EXT[extension] : undefined;
+    return mediaType ? { type: 'Image', url, mediaType } : { type: 'Image', url };
+}
+/**
+ * Build the actor `icon` (avatar) object, enforcing the absolute-URL invariant.
+ *
+ * ActivityPub consumers such as Mastodon validate that `icon.url` is an absolute
+ * URL and REJECT the entire actor document when it is not — so a non-absolute
+ * value makes the account undiscoverable. Returns undefined when there is no
+ * avatar or no absolute URL can be produced (Mastodon is fine with an
+ * avatar-less actor).
+ */
+function buildActorIcon(config, avatar) {
+    if (!avatar)
+        return undefined;
+    const resolved = config.media.resolveAvatar(avatar);
+    if (!resolved || !isAbsoluteHttpUrl(resolved)) {
+        config.onWarn?.(`[Federation] Omitting actor icon — avatar did not resolve to an absolute URL (ref: ${avatar})`);
+        return undefined;
+    }
+    return apImageObject(resolved);
+}
+/**
+ * Build the actor `image` (profile banner/header) object, enforcing the same
+ * absolute-URL invariant as {@link buildActorIcon}. Mastodon renders the AP
+ * `image` property as the profile HEADER banner.
+ */
+function buildActorImage(config, banner) {
+    if (!banner)
+        return undefined;
+    const resolved = config.media.resolveBanner(banner);
+    if (!resolved || !isAbsoluteHttpUrl(resolved)) {
+        config.onWarn?.(`[Federation] Omitting actor image — banner did not resolve to an absolute URL (ref: ${banner})`);
+        return undefined;
+    }
+    return apImageObject(resolved);
+}
+/**
+ * Build the per-instance local-actor builder. Bind it once with an app's domain +
+ * media resolver; call the returned function per user.
+ */
+export function createLocalActorBuilder(config) {
+    return (params) => {
+        const { username, displayName, kind, bio, avatar, profileHeaderImage, publicKey, createdAt } = params;
+        const actorObject = {
+            id: config.urls.actor(username),
+            type: localActorTypeForAccountKind(kind),
+            preferredUsername: username,
+            name: displayName,
+            summary: bio || '',
+            url: `https://${config.domain}/@${username}`,
+            inbox: config.urls.inbox(username),
+            outbox: config.urls.outbox(username),
+            featured: config.urls.featured(username),
+            followers: config.urls.followers(username),
+            following: config.urls.following(username),
+            endpoints: { sharedInbox: config.urls.sharedInbox() },
+            discoverable: true,
+            manuallyApprovesFollowers: false,
+            icon: buildActorIcon(config, avatar),
+            image: buildActorImage(config, profileHeaderImage),
+            publicKey: {
+                id: publicKey.keyId,
+                owner: config.urls.actor(username),
+                publicKeyPem: publicKey.publicKeyPem,
+            },
+        };
+        // `published` (account creation date) is advertised when the API provides it.
+        if (createdAt) {
+            actorObject.published = new Date(createdAt).toISOString();
+        }
+        return actorObject;
+    };
+}

package/dist/esm/apContext.js

@@ -0,0 +1,45 @@
+/**
+ * The shared JSON-LD `@context` every Oxy app emits on its ActivityPub actor and
+ * activity documents.
+ *
+ * These term declarations are LOAD-BEARING and must stay byte-identical across
+ * apps: a strict JSON-LD consumer DROPS any field whose term is not declared
+ * here, and Mastodon negative-caches a malformed actor for minutes/hours. The
+ * exact set below matches the proven Mention actor — `as:sensitive`, Mastodon's
+ * `toot:votersCount`, and the four interoperating quote-post terms
+ * (FEP-044f / FEP-e232 across Mastodon, Fedibird, Misskey and Pleroma/Akkoma).
+ */
+export const AP_CONTEXT = [
+    'https://www.w3.org/ns/activitystreams',
+    'https://w3id.org/security/v1',
+    // The AS2 core context above defines the `as:` prefix
+    // (`as` → `https://www.w3.org/ns/activitystreams#`), so this maps the Note's
+    // `sensitive` boolean to `as:sensitive` — the exact term Mastodon defines for
+    // it. Without the term declaration a JSON-LD consumer drops `sensitive`.
+    //
+    // `toot` is Mastodon's extension namespace; `votersCount` (the total unique
+    // voters on a poll `Question`) is `toot:votersCount` — the exact term Mastodon
+    // emits and reads. Without the declaration a JSON-LD consumer drops it. The
+    // `Question`/`oneOf`/`anyOf`/`endTime`/`closed` poll terms are all AS2 core, so
+    // they need no extra declaration here.
+    //
+    // Quote-post interop (FEP-044f / FEP-e232). A quote post carries the quoted
+    // object's canonical AP id under FOUR terms so the widest set of servers
+    // renders the inline quote: `quote` (FEP-044f, Mastodon 4.4+), `quoteUri`
+    // (Fedibird), `_misskey_quote` (Misskey) and `quoteUrl` (Pleroma/Akkoma). Each
+    // is typed `@id` (an IRI, not a literal); the `misskey`/`fedibird` namespaces
+    // and the AS2 `Link` type back the FEP-e232 `Link` quote tag. Without these
+    // declarations a strict JSON-LD consumer DROPS the quote fields.
+    {
+        sensitive: 'as:sensitive',
+        toot: 'http://joinmastodon.org/ns#',
+        votersCount: 'toot:votersCount',
+        misskey: 'https://misskey-hub.net/ns#',
+        fedibird: 'http://fedibird.com/ns#',
+        quote: { '@id': 'https://w3id.org/fep/044f#quote', '@type': '@id' },
+        quoteUri: { '@id': 'fedibird:quoteUri', '@type': '@id' },
+        quoteUrl: { '@id': 'as:quoteUrl', '@type': '@id' },
+        _misskey_quote: { '@id': 'misskey:_misskey_quote', '@type': '@id' },
+        Link: 'as:Link',
+    },
+];

package/dist/esm/apUri.js

@@ -0,0 +1,126 @@
+/**
+ * ActivityPub URI parsing + host canonicalisation + per-instance domain policy.
+ *
+ * `canonicalFederationHost` / `isSameFederationHost` are the one rule for "are
+ * these the same host", and every domain comparison the policy makes is built
+ * out of them. `extractActorUriFromActivityId` is pure and domain-agnostic. The
+ * blocked-domain check and the local-post-id extractor are DOMAIN-SCOPED — they
+ * depend on which hosts an app mints its own URIs under and which identity apex
+ * publishes its own users — so they come from a per-instance
+ * {@link createDomainPolicy} rather than a module-level constant.
+ */
+/** Path segments that typically separate an actor path from a post ID in ActivityPub URIs. */
+const POST_PATH_SEGMENTS = new Set(['statuses', 'posts', 'notes', 'objects', 'activities']);
+/**
+ * THE FORM THIS ENGINE COMPARES HOSTS IN — trimmed, lowercased, one leading
+ * `www.` removed, and nothing else.
+ *
+ * It is exported because it is not an implementation detail: it decides whether
+ * two spellings of a host are the SAME host, and {@link createDomainPolicy} —
+ * the blocked-domain gate every inbound activity and every actor fetch passes
+ * through — is built out of this exact function. A consumer that keeps its own
+ * copy of the rule (a moderation blocklist, a transparency page, a content
+ * purge) is keeping a second opinion about which hosts are which, and the moment
+ * the two drift the consumer acts on domains the engine never refused. For a
+ * consumer whose action is irreversible that difference is deleted content.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO
+ *
+ *   It does not strip a TRAILING DOT. `example.com.` is the fully-qualified
+ *   spelling of `example.com` in DNS, but it is a different string here — and
+ *   also on the wire, because `new URL('https://example.com./x').hostname`
+ *   preserves the dot and that value is what the engine feeds in. So the two
+ *   spellings do not match each other, in this function and in the engine
+ *   alike. Widening that is a POLICY decision (it makes a blocklist match hosts
+ *   it does not literally name) and belongs to whoever owns the policy, not to
+ *   a string transform.
+ *
+ *   It does not perform IDNA. The input is expected to be an ASCII host in the
+ *   form the WHATWG URL parser produces — `new URL(...).hostname` has already
+ *   applied ToASCII, so an internationalised host arrives as punycode
+ *   (`xn--ber-goa.example`). A host spelled in unicode is lowercased but NOT
+ *   converted, so it will not match its own punycode wire form. Callers that
+ *   accept operator-typed hosts must convert them before comparing.
+ *
+ * @param host a bare host — no scheme, no port, no path.
+ */
+export function canonicalFederationHost(host) {
+    const value = host.trim().toLowerCase();
+    return value.startsWith('www.') ? value.slice(4) : value;
+}
+/**
+ * Whether two spellings name the same host under {@link canonicalFederationHost}.
+ *
+ * This is the question a caller actually has ("is the host on this activity the
+ * host we blocked?"), and it exists so that asking it does not require each
+ * caller to assemble its own comparison around the normaliser. Assembling one is
+ * where the mistakes happen, and they are quiet ones: a comparison that
+ * lowercases but forgets `www.`, or that allows `www.` on one side only and so
+ * answers differently depending on argument order, looks correct at every call
+ * site and is wrong for exactly the hosts an evasive instance will use.
+ *
+ * A blank string names no host, so it matches nothing — including another blank.
+ * That is the same answer {@link DomainPolicy.isBlockedDomain} gives it: a host
+ * that is not named is not in any set.
+ */
+export function isSameFederationHost(a, b) {
+    const canonicalA = canonicalFederationHost(a);
+    if (canonicalA.length === 0)
+        return false;
+    return canonicalA === canonicalFederationHost(b);
+}
+/**
+ * Given an ActivityPub activity/object ID (URL), extract the actor URI by
+ * trimming everything from the first recognised post-path segment onward.
+ *
+ * e.g. "https://mastodon.social/users/alice/statuses/12345"
+ *    → "https://mastodon.social/users/alice"
+ *
+ * Returns null when the URL is malformed or no post-path segment is found.
+ */
+export function extractActorUriFromActivityId(activityId) {
+    try {
+        const url = new URL(activityId);
+        const segments = url.pathname.split('/').filter(Boolean);
+        const statusIdx = segments.findIndex((s) => POST_PATH_SEGMENTS.has(s));
+        if (statusIdx < 1)
+            return null;
+        return `${url.origin}/${segments.slice(0, statusIdx).join('/')}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build the per-instance {@link DomainPolicy} from an app's domain configuration.
+ */
+export function createDomainPolicy(config) {
+    const localDomains = new Set([
+        canonicalFederationHost(config.domain),
+        canonicalFederationHost(config.actorDomain ?? config.domain),
+    ]);
+    const identityApex = config.identityApex ? canonicalFederationHost(config.identityApex) : undefined;
+    const blocked = new Set();
+    for (const d of config.blockedDomains ?? []) {
+        blocked.add(canonicalFederationHost(d));
+    }
+    return {
+        isBlockedDomain(domain) {
+            const d = canonicalFederationHost(domain);
+            return localDomains.has(d) || (identityApex !== undefined && d === identityApex) || blocked.has(d);
+        },
+        extractLocalPostId(objectUri) {
+            let parsed;
+            try {
+                parsed = new URL(objectUri);
+            }
+            catch {
+                return null;
+            }
+            if (!localDomains.has(canonicalFederationHost(parsed.hostname)))
+                return null;
+            const match = parsed.pathname.match(/^\/ap\/users\/[^/]+\/posts\/([^/]+)\/?$/);
+            return match ? match[1] : null;
+        },
+    };
+}

package/dist/esm/httpSignature.js

@@ -0,0 +1,179 @@
+/**
+ * HTTP Signatures (draft-cavage-http-signatures-12) — the PURE sign/verify
+ * crypto that every Oxy app's ActivityPub federation shares.
+ *
+ * This is the highest-risk surface in the federation engine: the exact bytes of
+ * the signing string, the covered-header list and its order, the signature
+ * parameters, and the `X-Forwarded-Host` host reconstruction are what remote
+ * servers (Mastodon et al.) verify against. A one-character drift silently kills
+ * ALL federation, so this module is a byte-for-byte extraction of Mention's
+ * proven implementation — with the ONLY behavioural knobs made explicit:
+ *
+ *  - **private-key custody is injected** ({@link HttpSignatureSigner}). The
+ *    private key NEVER enters this package; the app supplies a `sign(keyId,
+ *    signingString)` that (for Mention) calls oxy-api `POST /federation/sign`.
+ *  - **`X-Forwarded-Host` trust is opt-in** ({@link VerifyHttpSignatureOptions.trustForwardedHost}).
+ *    Mention runs behind a CF-proxied apex that rewrites the origin `Host`, so it
+ *    passes `true`; a directly-exposed origin leaves it `false`.
+ *
+ * Lives in the isomorphic `.` entry (no Express / Mongoose): it depends only on
+ * the runtime `crypto` builtin (Node / Bun) and is never invoked from browser /
+ * React-Native bundles — RN consumers import only the connector TYPES, which are
+ * erased at compile time.
+ */
+import crypto from 'node:crypto';
+/** The signature algorithm parameter emitted in (and expected on) the `Signature` header. */
+export const HTTP_SIGNATURE_ALGORITHM = 'rsa-sha256';
+/**
+ * The default content-type folded into the signing string for body-bearing
+ * requests. ActivityPub delivery signs `content-type` (some servers — e.g.
+ * Threads — require it), and the AP content type is always
+ * `application/activity+json`.
+ */
+export const DEFAULT_SIGNED_CONTENT_TYPE = 'application/activity+json';
+/**
+ * Build the HTTP Signature header per draft-cavage-http-signatures-12 and sign it
+ * via the injected {@link HttpSignatureSigner} (the private key never enters this
+ * package).
+ *
+ * The spec-correct signing string is composed locally: `(request-target)`, host,
+ * date, and — for body-bearing requests — digest and content-type. The composed
+ * string is handed to `sign`, and the resulting signature is assembled into the
+ * `Signature:` header.
+ *
+ * Returns the headers to attach to the outbound request (Host, Date, optional
+ * Digest, and Signature). Content-Type is set by the deliverer's fetch.
+ */
+export async function signRequest(sign, keyId, method, url, body, options = {}) {
+    const contentType = options.contentType ?? DEFAULT_SIGNED_CONTENT_TYPE;
+    const parsedUrl = new URL(url);
+    const date = new Date().toUTCString();
+    const headers = {
+        Host: parsedUrl.host,
+        Date: date,
+    };
+    const signedHeaderNames = ['(request-target)', 'host', 'date'];
+    const signingParts = [
+        `(request-target): ${method.toLowerCase()} ${parsedUrl.pathname}${parsedUrl.search}`,
+        `host: ${parsedUrl.host}`,
+        `date: ${date}`,
+    ];
+    if (body) {
+        const digest = crypto.createHash('sha256').update(body).digest('base64');
+        headers.Digest = `SHA-256=${digest}`;
+        signedHeaderNames.push('digest');
+        signingParts.push(`digest: SHA-256=${digest}`);
+        // Include content-type in signature (required by some servers like Threads)
+        signedHeaderNames.push('content-type');
+        signingParts.push(`content-type: ${contentType}`);
+    }
+    const signingString = signingParts.join('\n');
+    const signature = await sign(keyId, signingString);
+    headers.Signature = [
+        `keyId="${keyId}"`,
+        `algorithm="${HTTP_SIGNATURE_ALGORITHM}"`,
+        `headers="${signedHeaderNames.join(' ')}"`,
+        `signature="${signature}"`,
+    ].join(',');
+    return headers;
+}
+/**
+ * Parse the Signature header from an incoming request.
+ */
+function parseSignatureHeader(signatureHeader) {
+    const params = {};
+    const regex = /(\w+)="([^"]*)"/g;
+    let match = regex.exec(signatureHeader);
+    while (match !== null) {
+        params[match[1]] = match[2];
+        match = regex.exec(signatureHeader);
+    }
+    if (!params.keyId || !params.signature)
+        return null;
+    return {
+        keyId: params.keyId,
+        algorithm: params.algorithm || HTTP_SIGNATURE_ALGORITHM,
+        headers: (params.headers || 'date').split(' '),
+        signature: params.signature,
+    };
+}
+/**
+ * Verify the HTTP signature on an incoming request.
+ * Returns the actor URI (key owner) if valid, null otherwise.
+ */
+export async function verifyHttpSignature(req, fetchPublicKey, options = {}) {
+    const signatureHeader = req.headers.signature;
+    if (!signatureHeader)
+        return { verified: false, reason: 'missing-signature' };
+    const parsed = parseSignatureHeader(signatureHeader);
+    if (!parsed)
+        return { verified: false, reason: 'invalid-signature-header' };
+    const keyData = await fetchPublicKey(parsed.keyId);
+    if (!keyData) {
+        options.onDebug?.(`Failed to fetch public key for keyId: ${parsed.keyId}`);
+        return { verified: false, reason: 'key-fetch-failed' };
+    }
+    const lowerHeaders = Object.fromEntries(Object.entries(req.headers).map(([k, v]) => [k.toLowerCase(), v]));
+    // Enforce Date skew (+/- 10 minutes) if present
+    const dateHeader = lowerHeaders.date;
+    if (dateHeader) {
+        const dateVal = Array.isArray(dateHeader) ? dateHeader[0] : dateHeader;
+        const parsedDate = Date.parse(dateVal || '');
+        if (!Number.isNaN(parsedDate)) {
+            const skew = Math.abs(Date.now() - parsedDate);
+            if (skew > 10 * 60 * 1000) {
+                return { verified: false, reason: 'date-skew' };
+            }
+        }
+    }
+    // If Digest header is required in signature but missing/invalid, fail early
+    if (parsed.headers.includes('digest')) {
+        const digestHeader = lowerHeaders.digest;
+        const bodyString = typeof req.body === 'string' ? req.body : req.body ? JSON.stringify(req.body) : '';
+        if (!digestHeader) {
+            return { verified: false, reason: 'missing-digest' };
+        }
+        const expectedDigest = `SHA-256=${crypto.createHash('sha256').update(bodyString).digest('base64')}`;
+        const digestVal = Array.isArray(digestHeader) ? digestHeader[0] : digestHeader;
+        if (digestVal !== expectedDigest) {
+            return { verified: false, reason: 'digest-mismatch' };
+        }
+    }
+    const signingParts = parsed.headers.map((header) => {
+        const name = header.toLowerCase();
+        if (name === '(request-target)') {
+            return `(request-target): ${req.method.toLowerCase()} ${req.path}`;
+        }
+        // Reconstruct the `host` line from `x-forwarded-host` when the caller trusts
+        // it (an edge that rewrites the origin Host forwards the ORIGINAL signed host
+        // here; a proxy chain's FIRST comma token is the client-facing host). See
+        // VerifyHttpSignatureOptions.trustForwardedHost. Falls back to `host` when the
+        // header is absent (direct delivery), preserving direct-delivery behavior.
+        if (name === 'host' && options.trustForwardedHost) {
+            const forwarded = lowerHeaders['x-forwarded-host'];
+            const forwardedValue = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+            const firstToken = forwardedValue?.split(',')[0]?.trim();
+            if (firstToken) {
+                return `host: ${firstToken}`;
+            }
+        }
+        const value = lowerHeaders[name];
+        return `${name}: ${Array.isArray(value) ? value[0] : value}`;
+    });
+    const signingString = signingParts.join('\n');
+    const verifier = crypto.createVerify('sha256');
+    verifier.update(signingString);
+    verifier.end();
+    try {
+        const isValid = verifier.verify(keyData.publicKeyPem, parsed.signature, 'base64');
+        return {
+            verified: isValid,
+            actorUri: isValid ? keyData.actorUri : undefined,
+            reason: isValid ? undefined : 'verify-failed',
+        };
+    }
+    catch (err) {
+        options.onDebug?.('HTTP signature verification failed:', err);
+        return { verified: false, reason: err instanceof Error ? err.message : 'verify-exception' };
+    }
+}

package/dist/esm/index.js

@@ -0,0 +1,65 @@
+/**
+ * @oxy.so/federation — the app-agnostic federation substrate (isomorphic `.` entry).
+ *
+ * The pluggable network-connector CONTRACT and the normalized, cross-network
+ * DTOs every connector produces. An app's content/MTN core never knows about
+ * Mastodon (ActivityPub) or Bluesky (atproto); it only ever talks to a
+ * {@link NetworkConnector}. This module is that seam: the normalized DTOs every
+ * connector produces, the local-event union connectors deliver outbound, and
+ * the connector interface itself.
+ *
+ * IMPORTANT: this entry is intentionally free of Mongoose / Express / React
+ * Native so it can be imported from any Oxy app backend (and, in later phases,
+ * share the pure HTTP-signature + actor-object surface with browser/isomorphic
+ * callers). The runnable Express/Node engine — signed fetch, delivery transport,
+ * webfinger/actor/inbox routers, remote-actor resolution — lives under the
+ * separate `./node` subpath so it never enters isomorphic bundles.
+ *
+ * The one piece of app-specific data that flows through the outbound seam — a
+ * local post's canonical content — is a TYPE PARAMETER (`TContent`), supplied by
+ * the consuming app (Mention passes its `PostContent`). The engine holds no
+ * knowledge of any app's post shape.
+ */
+/**
+ * HTTP Signatures (draft-cavage) — the pure sign/verify crypto every Oxy app's
+ * ActivityPub federation shares. Private-key custody is injected; the key never
+ * enters this package.
+ */
+export { signRequest, verifyHttpSignature, HTTP_SIGNATURE_ALGORITHM, DEFAULT_SIGNED_CONTENT_TYPE, } from './httpSignature.js';
+/**
+ * Domain-parameterized ActivityPub URL builders — each app instantiates them once
+ * with its own `FEDERATION_DOMAIN` so every actor stays `@user@its-own-domain`.
+ */
+export { createUrlBuilders, normalizeActorUsername, INSTANCE_ACTOR_USERNAME } from './urls.js';
+/**
+ * Network identity: the MECHANISM for re-labelling an account republished by a
+ * bridge onto the network it actually came from, plus the network vocabulary and
+ * the bidirectional upstream-profile-URL rule.
+ *
+ * The mechanism is here; the ENTRIES are not, and must not be. Which operators
+ * may be trusted to re-attribute somebody's account is a moderation judgement an
+ * app commits and answers for — `createBridgeRelabeller` takes them as a
+ * parameter so no app inherits another's.
+ */
+export { FEDERATION_NETWORKS, BSKY_NETWORK_DOMAIN, blueskyUsernameFromHandle, createBridgeRelabeller, stripBridgeBoilerplate, upstreamProfileUrl, parseUpstreamProfileUrl, federatedUsernameFromUpstreamUrl, upstreamHandleFromProfileField, upstreamHandleFromAlsoKnownAs, upstreamHandleFromAutomatedActor, upstreamHandleFromPreferredUsername, upstreamHandleFromProxyOf, readProxyDeclarations, } from './networkIdentity.js';
+/**
+ * The shared JSON-LD `@context` (load-bearing term declarations) and the
+ * ActivityPub URI helpers (actor-uri extraction + the per-instance domain policy:
+ * blocked-domain check + local-post-id extraction).
+ *
+ * `canonicalFederationHost` / `isSameFederationHost` are exported because the
+ * domain policy is not the only thing that has to decide whether two spellings
+ * are the same host: a moderation blocklist, a transparency page and a content
+ * purge all ask the same question about the same hosts, and any of them keeping
+ * its own copy of the rule is a second opinion waiting to diverge from the one
+ * the engine enforces. They are the very functions {@link createDomainPolicy} is
+ * built from — not a parallel implementation that agrees today.
+ */
+export { AP_CONTEXT } from './apContext.js';
+export { canonicalFederationHost, isSameFederationHost, extractActorUriFromActivityId, createDomainPolicy, } from './apUri.js';
+/**
+ * The single builder of a LOCAL user's ActivityPub actor document —
+ * byte-identical across apps, with media resolution injected. The actor `type`
+ * follows the Oxy account kind ({@link LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND}).
+ */
+export { createLocalActorBuilder, localActorTypeForAccountKind, isApActorType, AP_ACTOR_TYPES, LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND, } from './actorObject.js';