@oxy.so/federation 2.0.0 → 2.1.1

package/dist/types/actorObject.d.ts

@@ -168,6 +168,16 @@ export interface BuildLocalActorParams {
         publicKeyPem: string;
     };
     createdAt?: string | null;
+    /**
+     * The actor URIs this account is ALSO known as — the ActivityPub
+     * `alsoKnownAs` a Mastodon `Move` checks before it lets followers follow the
+     * account here. Oxy derives it from the user's live, ownership-proven linked
+     * accounts; the builder only publishes it. Omitted from the document when
+     * absent or empty (an empty array is not a claim worth making), de-duplicated,
+     * and restricted to absolute `https:` URIs, because a receiver dereferences
+     * each one.
+     */
+    alsoKnownAs?: readonly string[] | null;
 }
 /**
  * Assembles a LOCAL user's AP actor object (WITHOUT the top-level `@context`).
@@ -175,6 +185,12 @@ export interface BuildLocalActorParams {
  * {@link LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND}.
  */
 export type LocalActorBuilder = (params: BuildLocalActorParams) => Record<string, unknown>;
+/**
+ * The publishable subset of an `alsoKnownAs` input: absolute `https:` URIs,
+ * first occurrence wins, input order kept. Exported so every actor builder
+ * (Oxy's own included) applies the same rule.
+ */
+export declare function normalizeAlsoKnownAs(values: readonly string[] | null | undefined): string[];
 /**
  * Build the per-instance local-actor builder. Bind it once with an app's domain +
  * media resolver; call the returned function per user.

package/dist/types/apContext.d.ts

@@ -10,6 +10,10 @@
  * (FEP-044f / FEP-e232 across Mastodon, Fedibird, Misskey and Pleroma/Akkoma).
  */
 export declare const AP_CONTEXT: (string | {
+    alsoKnownAs: {
+        '@id': string;
+        '@type': string;
+    };
     sensitive: string;
     toot: string;
     votersCount: string;

package/dist/types/index.d.ts

@@ -62,7 +62,7 @@ export { canonicalFederationHost, isSameFederationHost, extractActorUriFromActiv
  * 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, type ApActorType, type LocalActorType, type LocalActorBuilder, type LocalActorBuilderConfig, type BuildLocalActorParams, type ActorMediaResolver, } from './actorObject';
+export { createLocalActorBuilder, normalizeAlsoKnownAs, localActorTypeForAccountKind, isApActorType, AP_ACTOR_TYPES, LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND, type ApActorType, type LocalActorType, type LocalActorBuilder, type LocalActorBuilderConfig, type BuildLocalActorParams, type ActorMediaResolver, } from './actorObject';
 /** Supported external networks. */
 export type NetworkId = 'activitypub' | 'atproto';
 /**

package/dist/types/node/actorRouter.d.ts

@@ -35,6 +35,12 @@ export interface ActorRouteUser {
     createdAt?: string | null;
     /** Account-graph classification — decides the actor `type`. */
     kind?: AccountKind | null;
+    /**
+     * The actor URIs Oxy publishes as this account's aliases
+     * (`GET /profiles/username/:username` → `alsoKnownAs`). Emitted on the actor
+     * only when non-empty.
+     */
+    alsoKnownAs?: readonly string[] | null;
     _count?: {
         followers?: number;
         following?: number;

package/dist/types/node/delivery.d.ts

@@ -164,6 +164,12 @@ export interface DeliveryActorProfile {
      * staleness window).
      */
     kind?: AccountKind | null;
+    /**
+     * The aliases Oxy publishes for the account. Must travel with the `Update`
+     * for the same reason `kind` does: the pushed actor and the fetched actor are
+     * one document, and a follower's instance learns a new alias from this push.
+     */
+    alsoKnownAs?: readonly string[] | null;
 }
 /** Resolve a local username to its Oxy profile (for the `Update(Person)` rebroadcast). */
 export interface DeliveryIdentity {

package/dist/types/node/inboundDispatch.d.ts

@@ -12,6 +12,12 @@
  * post/engagement handlers live. The consent gate + notification side effects are
  * injected so the engine holds no app knowledge.
  *
+ * `Move` (account migration) is handed to {@link InboundDispatcherConfig.onMove}
+ * after a SHAPE check only: the engine proves the activity is the signing actor
+ * moving itself, and the app forwards it to Oxy (`POST /federation/move`), which
+ * owns the identity decision — the alias check and the re-fetch of the old
+ * actor's `movedTo`.
+ *
  * Extracted behaviour-identically from Mention's former `InboxProcessingService`
  * dispatcher + `handleIncomingFollow` / `handleUndo(Follow)` / `handleAccept` /
  * `handleReject`.
@@ -144,9 +150,25 @@ export interface InboundDispatcherConfig {
      * Delete / Update, and a non-follow Undo. The app's post/engagement handlers.
      */
     onContentActivity(activity: Record<string, unknown>, verifiedActorUri: string): Promise<void>;
+    /**
+     * Handle an account `Move` whose shape the engine has verified: signed by
+     * `oldActorUri`, which is both its `actor` and its `object`, naming a
+     * `targetActorUri`. The app forwards it to Oxy (`POST /federation/move`),
+     * which decides. Absent ⇒ a Move is logged and dropped.
+     */
+    onMove?(move: InboundMove): Promise<void>;
     /** Diagnostics sink. */
     logger: InboundDispatcherLogger;
 }
+/** A shape-verified inbound `Move`. Nothing here is trusted beyond the signature. */
+export interface InboundMove {
+    /** The activity `id`, the idempotency key Oxy records. */
+    activityId: string;
+    /** The account that is moving — the verified signer, its `actor` and its `object`. */
+    oldActorUri: string;
+    /** Where it says it moved. Oxy checks this names a local account that aliases the old one. */
+    targetActorUri: string;
+}
 /** The inbound-activity dispatcher. */
 export interface InboundDispatcher {
     /** Process one already-actor-verified inbound activity. */

package/dist/types/node/index.d.ts

@@ -41,7 +41,7 @@ export { createDeliveryService, type DeliveryService, type DeliveryServiceConfig
  * identity + store adapters, and the `onContentActivity` seam every content verb
  * (Create / Announce / Like / Delete / Update, non-follow Undo) is handed to.
  */
-export { createInboundDispatcher, ActorResolutionPendingError, type InboundDispatcher, type InboundDispatcherConfig, type InboundDispatcherLogger, type InboundActivityValidation, type InboundLocalUser, type InboundIdentity, type InboundConsent, type InboundActorResolver, type InboundFollowStore, type InboundDelivery, } from './inboundDispatch';
+export { createInboundDispatcher, ActorResolutionPendingError, type InboundMove, type InboundDispatcher, type InboundDispatcherConfig, type InboundDispatcherLogger, type InboundActivityValidation, type InboundLocalUser, type InboundIdentity, type InboundConsent, type InboundActorResolver, type InboundFollowStore, type InboundDelivery, } from './inboundDispatch';
 /** The WebFinger + host-meta discovery router (domain-parameterized, consent-gated). */
 export { createWebfingerRouter, type WebfingerRouterConfig, type WebfingerSharingState, type WebfingerUser, type WebfingerJrd, type WebfingerLogger, } from './webfingerRouter';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/federation",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Oxy Federation — the app-agnostic ActivityPub identity + follow engine substrate: the network-connector contract, normalized cross-network DTOs, HTTP signatures, actor resolution, the outbound delivery transport + follow lifecycle, the inbound dispatcher, and the webfinger/actor/inbox Express routers. Domain-parameterized so every Oxy app backend federates under its own domain.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -93,7 +93,7 @@
     }
   },
   "dependencies": {
-    "@oxy.so/contracts": "^1.0.0",
+    "@oxy.so/contracts": "^1.0.0 || ^2.0.0",
     "@oxy.so/core": "^1.0.0"
   },
   "peerDependencies": {

package/src/__tests__/actorObject.test.ts

@@ -102,6 +102,7 @@ describe('createLocalActorBuilder (golden actor vector)', () => {
       toot: 'http://joinmastodon.org/ns#',
       votersCount: 'toot:votersCount',
       quote: { '@id': 'https://w3id.org/fep/044f#quote', '@type': '@id' },
+      alsoKnownAs: { '@id': 'as:alsoKnownAs', '@type': '@id' },
     });
   });
 
@@ -248,6 +249,32 @@ describe('actor type by Oxy account kind', () => {
   });
 });
 
+describe('createLocalActorBuilder — alsoKnownAs', () => {
+  const alias = 'https://mastodon.social/users/nate';
+
+  it('emits nothing when there are no aliases, so ordinary actors stay byte-identical', () => {
+    for (const alsoKnownAs of [undefined, null, []]) {
+      const actor = buildActor({ ...PARAMS, alsoKnownAs });
+      expect(actor).not.toHaveProperty('alsoKnownAs');
+      expect(JSON.stringify(actor)).toBe(JSON.stringify(EXPECTED_ACTOR));
+    }
+  });
+
+  it('emits the aliases after publicKey, de-duplicated and https-only', () => {
+    const actor = buildActor({
+      ...PARAMS,
+      alsoKnownAs: [alias, 'http://insecure.example/users/nate', 'not a url', alias, 'https://pleroma.example/users/n'],
+    });
+    expect(actor.alsoKnownAs).toEqual([alias, 'https://pleroma.example/users/n']);
+    const keys = Object.keys(actor);
+    expect(keys.indexOf('alsoKnownAs')).toBe(keys.indexOf('publicKey') + 1);
+  });
+
+  it('emits nothing when every alias is unpublishable', () => {
+    expect(buildActor({ ...PARAMS, alsoKnownAs: ['http://x.example/u'] })).not.toHaveProperty('alsoKnownAs');
+  });
+});
+
 describe('createUrlBuilders', () => {
   it('scopes actor() to actorDomain and the rest to domain', () => {
     const urls = createUrlBuilders('mention.earth', 'actors.mention.earth');

package/src/__tests__/inboundDispatch.test.ts

@@ -29,7 +29,9 @@ function makeRig(overrides: {
   actorOxyUserIdForUndo?: string | null;
   validate?: (activity: Record<string, unknown>) => InboundActivityValidation;
   blockedHosts?: string[];
+  withMoveHandler?: boolean;
 } = {}) {
+  const moves: Array<{ activityId: string; oldActorUri: string; targetActorUri: string }> = [];
   const bridgeFollowCalls: Array<[string, string]> = [];
   const bridgeUnfollowCalls: Array<[string, string]> = [];
   const acceptsSent: Array<{ localOxyUserId: string; localUsername: string; followActivityId: string; remoteActorUri: string }> = [];
@@ -106,11 +108,19 @@ function makeRig(overrides: {
     onContentActivity: async (activity, verifiedActorUri) => {
       contentActivities.push({ type: activity.type, verifiedActorUri });
     },
+    ...(overrides.withMoveHandler === false
+      ? {}
+      : {
+          onMove: async (move: { activityId: string; oldActorUri: string; targetActorUri: string }) => {
+            moves.push(move);
+          },
+        }),
     logger: { debug: () => {}, info: () => {}, warn: () => {} },
   };
 
   return {
     dispatcher: createInboundDispatcher(config),
+    moves,
     validatedActivities,
     bridgeFollowCalls,
     bridgeUnfollowCalls,
@@ -249,6 +259,56 @@ describe('inbound Accept / Reject', () => {
   });
 });
 
+describe('Move → onMove', () => {
+  const TARGET = 'https://mention.earth/ap/users/bob';
+  const move = (extra: Record<string, unknown> = {}) => ({
+    id: `${REMOTE_ACTOR}#moves/1`,
+    type: 'Move',
+    actor: REMOTE_ACTOR,
+    object: REMOTE_ACTOR,
+    target: TARGET,
+    ...extra,
+  });
+
+  it('hands a well-formed self-Move to the app', async () => {
+    const rig = makeRig();
+    await rig.dispatcher.processInboxActivity(move(), REMOTE_ACTOR);
+    expect(rig.moves).toEqual([{ activityId: `${REMOTE_ACTOR}#moves/1`, oldActorUri: REMOTE_ACTOR, targetActorUri: TARGET }]);
+    expect(rig.contentActivities).toHaveLength(0);
+  });
+
+  it('accepts embedded object/target references', async () => {
+    const rig = makeRig();
+    await rig.dispatcher.processInboxActivity(move({ object: { id: REMOTE_ACTOR }, target: { id: TARGET } }), REMOTE_ACTOR);
+    expect(rig.moves).toHaveLength(1);
+  });
+
+  it.each([
+    ['a Move of someone else', { object: 'https://remote.example/users/carol' }],
+    ['an actor that is not the signer', { actor: 'https://remote.example/users/carol' }],
+    ['no target', { target: undefined }],
+    ['a non-https target', { target: 'http://mention.earth/ap/users/bob' }],
+    ['a target equal to the mover', { target: REMOTE_ACTOR }],
+    ['no activity id', { id: undefined }],
+  ])('drops %s', async (_label, extra) => {
+    const rig = makeRig();
+    await rig.dispatcher.processInboxActivity(move(extra), REMOTE_ACTOR);
+    expect(rig.moves).toHaveLength(0);
+  });
+
+  it('drops a Move signed by a different actor than it names', async () => {
+    const rig = makeRig();
+    await rig.dispatcher.processInboxActivity(move(), 'https://relay.example/actor');
+    expect(rig.moves).toHaveLength(0);
+  });
+
+  it('drops a Move when the app registered no handler', async () => {
+    const rig = makeRig({ withMoveHandler: false });
+    await expect(rig.dispatcher.processInboxActivity(move(), REMOTE_ACTOR)).resolves.toBeUndefined();
+    expect(rig.contentActivities).toHaveLength(0);
+  });
+});
+
 describe('content verbs → onContentActivity', () => {
   it.each(['Create', 'Announce', 'Like', 'Delete', 'Update'])('routes %s to the app', async (type) => {
     const rig = makeRig();

package/src/actorObject.ts

@@ -222,6 +222,16 @@ export interface BuildLocalActorParams {
   profileHeaderImage?: string | null;
   publicKey: { keyId: string; publicKeyPem: string };
   createdAt?: string | null;
+  /**
+   * The actor URIs this account is ALSO known as — the ActivityPub
+   * `alsoKnownAs` a Mastodon `Move` checks before it lets followers follow the
+   * account here. Oxy derives it from the user's live, ownership-proven linked
+   * accounts; the builder only publishes it. Omitted from the document when
+   * absent or empty (an empty array is not a claim worth making), de-duplicated,
+   * and restricted to absolute `https:` URIs, because a receiver dereferences
+   * each one.
+   */
+  alsoKnownAs?: readonly string[] | null;
 }
 
 /**
@@ -271,6 +281,28 @@ function buildActorImage(
   return apImageObject(resolved);
 }
 
+/**
+ * The publishable subset of an `alsoKnownAs` input: absolute `https:` URIs,
+ * first occurrence wins, input order kept. Exported so every actor builder
+ * (Oxy's own included) applies the same rule.
+ */
+export function normalizeAlsoKnownAs(values: readonly string[] | null | undefined): string[] {
+  if (!values) return [];
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values) {
+    if (typeof value !== 'string' || seen.has(value)) continue;
+    try {
+      if (new URL(value).protocol !== 'https:') continue;
+    } catch {
+      continue;
+    }
+    seen.add(value);
+    result.push(value);
+  }
+  return result;
+}
+
 /**
  * Build the per-instance local-actor builder. Bind it once with an app's domain +
  * media resolver; call the returned function per user.
@@ -303,6 +335,11 @@ export function createLocalActorBuilder(config: LocalActorBuilderConfig): LocalA
       },
     };
 
+    const aliases = normalizeAlsoKnownAs(params.alsoKnownAs);
+    if (aliases.length > 0) {
+      actorObject.alsoKnownAs = aliases;
+    }
+
     // `published` (account creation date) is advertised when the API provides it.
     if (createdAt) {
       actorObject.published = new Date(createdAt).toISOString();

package/src/apContext.ts

@@ -30,7 +30,12 @@ export const AP_CONTEXT = [
   // 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.
+  //
+  // `alsoKnownAs` is the account-alias term a Mastodon `Move` verifies. It is
+  // `as:alsoKnownAs` typed `@id`, exactly as Mastodon declares it; without the
+  // declaration a strict consumer drops the aliases and the move is refused.
   {
+    alsoKnownAs: { '@id': 'as:alsoKnownAs', '@type': '@id' },
     sensitive: 'as:sensitive',
     toot: 'http://joinmastodon.org/ns#',
     votersCount: 'toot:votersCount',

package/src/index.ts

@@ -112,6 +112,7 @@ export {
  */
 export {
   createLocalActorBuilder,
+  normalizeAlsoKnownAs,
   localActorTypeForAccountKind,
   isApActorType,
   AP_ACTOR_TYPES,

package/src/node/actorRouter.ts

@@ -41,6 +41,12 @@ export interface ActorRouteUser {
   createdAt?: string | null;
   /** Account-graph classification — decides the actor `type`. */
   kind?: AccountKind | null;
+  /**
+   * The actor URIs Oxy publishes as this account's aliases
+   * (`GET /profiles/username/:username` → `alsoKnownAs`). Emitted on the actor
+   * only when non-empty.
+   */
+  alsoKnownAs?: readonly string[] | null;
   _count?: { followers?: number; following?: number } | null;
 }
 
@@ -388,6 +394,7 @@ export function createActorRouter(config: ActorRouterConfig): Router {
         profileHeaderImage,
         publicKey,
         createdAt: user.createdAt,
+        alsoKnownAs: user.alsoKnownAs,
       });
 
       res.set('Content-Type', apContentType);

package/src/node/delivery.ts

@@ -177,6 +177,12 @@ export interface DeliveryActorProfile {
    * staleness window).
    */
   kind?: AccountKind | null;
+  /**
+   * The aliases Oxy publishes for the account. Must travel with the `Update`
+   * for the same reason `kind` does: the pushed actor and the fetched actor are
+   * one document, and a follower's instance learns a new alias from this push.
+   */
+  alsoKnownAs?: readonly string[] | null;
 }
 
 /** Resolve a local username to its Oxy profile (for the `Update(Person)` rebroadcast). */
@@ -695,6 +701,7 @@ export function createDeliveryService<TActor extends DeliveryActorFields>(
         profileHeaderImage,
         publicKey,
         createdAt: user.createdAt,
+        alsoKnownAs: user.alsoKnownAs,
       });
 
       const actor = urls.actor(username);

package/src/node/inboundDispatch.ts

@@ -12,6 +12,12 @@
  * post/engagement handlers live. The consent gate + notification side effects are
  * injected so the engine holds no app knowledge.
  *
+ * `Move` (account migration) is handed to {@link InboundDispatcherConfig.onMove}
+ * after a SHAPE check only: the engine proves the activity is the signing actor
+ * moving itself, and the app forwards it to Oxy (`POST /federation/move`), which
+ * owns the identity decision — the alias check and the re-fetch of the old
+ * actor's `movedTo`.
+ *
  * Extracted behaviour-identically from Mention's former `InboxProcessingService`
  * dispatcher + `handleIncomingFollow` / `handleUndo(Follow)` / `handleAccept` /
  * `handleReject`.
@@ -159,10 +165,56 @@ export interface InboundDispatcherConfig {
    * Delete / Update, and a non-follow Undo. The app's post/engagement handlers.
    */
   onContentActivity(activity: Record<string, unknown>, verifiedActorUri: string): Promise<void>;
+  /**
+   * Handle an account `Move` whose shape the engine has verified: signed by
+   * `oldActorUri`, which is both its `actor` and its `object`, naming a
+   * `targetActorUri`. The app forwards it to Oxy (`POST /federation/move`),
+   * which decides. Absent ⇒ a Move is logged and dropped.
+   */
+  onMove?(move: InboundMove): Promise<void>;
   /** Diagnostics sink. */
   logger: InboundDispatcherLogger;
 }
 
+/** A shape-verified inbound `Move`. Nothing here is trusted beyond the signature. */
+export interface InboundMove {
+  /** The activity `id`, the idempotency key Oxy records. */
+  activityId: string;
+  /** The account that is moving — the verified signer, its `actor` and its `object`. */
+  oldActorUri: string;
+  /** Where it says it moved. Oxy checks this names a local account that aliases the old one. */
+  targetActorUri: string;
+}
+
+/**
+ * The shape check for an inbound `Move`.
+ *
+ * A Move is only meaningful as an actor moving ITSELF: `actor` and `object` must
+ * both be the actor whose HTTP signature was verified, so a relay or a third
+ * party cannot move somebody else's followers. `target` must be an absolute
+ * https URI, and differ from the old actor.
+ */
+function parseInboundMove(
+  activity: Record<string, unknown>,
+  verifiedActorUri: string,
+): { ok: true; move: InboundMove } | { ok: false; reason: string } {
+  const activityId = typeof activity.id === 'string' ? activity.id : undefined;
+  if (!activityId) return { ok: false, reason: 'missing id' };
+  const actor = objectTargetUri(activity.actor);
+  if (actor !== verifiedActorUri) return { ok: false, reason: 'actor is not the signer' };
+  const object = objectTargetUri(activity.object);
+  if (object !== verifiedActorUri) return { ok: false, reason: 'object is not the moving actor' };
+  const target = objectTargetUri(activity.target);
+  if (!target) return { ok: false, reason: 'missing target' };
+  try {
+    if (new URL(target).protocol !== 'https:') return { ok: false, reason: 'target is not https' };
+  } catch {
+    return { ok: false, reason: 'target is not a URL' };
+  }
+  if (target === verifiedActorUri) return { ok: false, reason: 'target is the moving actor' };
+  return { ok: true, move: { activityId, oldActorUri: verifiedActorUri, targetActorUri: target } };
+}
+
 /** The inbound-activity dispatcher. */
 export interface InboundDispatcher {
   /** Process one already-actor-verified inbound activity. */
@@ -411,6 +463,19 @@ export function createInboundDispatcher(config: InboundDispatcherConfig): Inboun
       case 'Update':
         await config.onContentActivity(activity, verifiedActorUri);
         break;
+      case 'Move': {
+        const parsed = parseInboundMove(activity, verifiedActorUri);
+        if (!parsed.ok) {
+          logger.warn(`[Federation] dropping Move from ${verifiedActorUri}: ${parsed.reason}`);
+          break;
+        }
+        if (!config.onMove) {
+          logger.debug(`Unhandled Move from ${verifiedActorUri} (no onMove handler)`);
+          break;
+        }
+        await config.onMove(parsed.move);
+        break;
+      }
       default:
         logger.debug(`Unhandled activity type: ${validation.type}`);
     }

package/src/node/index.ts

@@ -101,6 +101,7 @@ export {
 export {
   createInboundDispatcher,
   ActorResolutionPendingError,
+  type InboundMove,
   type InboundDispatcher,
   type InboundDispatcherConfig,
   type InboundDispatcherLogger,