@oxy.so/federation 2.4.2 → 2.5.0

package/dist/cjs/actorObject.js

@@ -22,6 +22,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND = exports.AP_ACTOR_TYPES = void 0;
 exports.isApActorType = isApActorType;
 exports.localActorTypeForAccountKind = localActorTypeForAccountKind;
+exports.accountKindForActor = accountKindForActor;
 exports.normalizeAlsoKnownAs = normalizeAlsoKnownAs;
 exports.createLocalActorBuilder = createLocalActorBuilder;
 const contracts_1 = require("@oxy.so/contracts");
@@ -46,7 +47,10 @@ function isApActorType(value) {
     return typeof value === 'string' && exports.AP_ACTOR_TYPES.includes(value);
 }
 /**
- * Oxy account kind → the AS2 actor type the fediverse is told about it.
+ * Oxy account kind → the AS2 actor type the fediverse is told about it — the
+ * ONE table both directions read: what Oxy announces for its own accounts here,
+ * and, through {@link accountKindForActor}, what it records a remote actor as.
+ * Changing how a kind federates is an edit to this table and nowhere else.
  *
  * `satisfies Record<AccountKind, LocalActorType>` is the load-bearing part: a
  * kind added to `@oxy.so/contracts` fails THIS build rather than silently
@@ -78,6 +82,8 @@ function isApActorType(value) {
  *    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.
+ *  - **`community` → `Group`.** A forum its members post into and that
+ *    re-broadcasts them: exactly what Lemmy, Mbin and Friendica mean by `Group`.
  *
  * 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
@@ -92,6 +98,7 @@ exports.LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND = {
     project: 'Organization',
     bot: 'Service',
     channel: 'Organization',
+    community: 'Group',
 };
 /**
  * The AS2 actor type for an Oxy account kind, defaulting to `Person`.
@@ -108,6 +115,49 @@ exports.LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND = {
 function localActorTypeForAccountKind(kind) {
     return (0, contracts_1.isAccountKind)(kind) ? exports.LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND[kind] : 'Person';
 }
+/**
+ * The inverse of {@link LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND}, derived from it. Three
+ * kinds share `Organization`, so a type reads back as the FIRST kind the table
+ * lists for it (`Organization` → `organization`); nothing on the wire tells a
+ * remote project from a remote organization.
+ */
+const ACCOUNT_KIND_BY_LOCAL_ACTOR_TYPE = (() => {
+    const inverse = new Map();
+    for (const [kind, type] of Object.entries(exports.LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND)) {
+        if (!inverse.has(type))
+            inverse.set(type, kind);
+    }
+    return inverse;
+})();
+/**
+ * AS2 actor types Oxy never announces but receives, and the announced type each
+ * is read as. `Application` is a non-human software actor — what `Service`
+ * already says, and half of Mastodon's own `bot?`.
+ */
+const INBOUND_ACTOR_TYPE_ALIASES = new Map([
+    ['Application', 'Service'],
+]);
+/**
+ * The kind a `Group` that only its moderators may post into is recorded as.
+ * Such a group forwards nobody: it PUBLISHES (a PeerTube video channel, a
+ * WordPress multi-author blog), which is what an Oxy channel is. The one
+ * inbound signal the table above has no column for.
+ */
+const MODERATED_GROUP_KIND = 'channel';
+/**
+ * The Oxy account kind a REMOTE actor is recorded as, read from the same table
+ * the local announcement uses ({@link LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND}). A type
+ * the table does not know (absent, misspelt, an extension type) is `personal`,
+ * the same default {@link localActorTypeForAccountKind} announces.
+ */
+function accountKindForActor(actor) {
+    if (typeof actor.type !== 'string')
+        return 'personal';
+    const type = INBOUND_ACTOR_TYPE_ALIASES.get(actor.type) ?? actor.type;
+    if (type === exports.LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND.community && actor.postingRestrictedToMods === true)
+        return MODERATED_GROUP_KIND;
+    return ACCOUNT_KIND_BY_LOCAL_ACTOR_TYPE.get(type) ?? 'personal';
+}
 /** Map common image extensions to a MIME type for an actor image `mediaType`. */
 const IMAGE_MEDIA_TYPE_BY_EXT = {
     png: 'image/png',

package/dist/cjs/index.js

@@ -22,7 +22,7 @@
  * knowledge of any app's post shape.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND = exports.AP_ACTOR_TYPES = exports.isApActorType = exports.localActorTypeForAccountKind = exports.normalizeAlsoKnownAs = exports.createLocalActorBuilder = exports.createDomainPolicy = exports.extractActorUriFromActivityId = exports.isSameFederationHost = exports.canonicalFederationHost = exports.AP_CONTEXT = exports.readProxyDeclarations = exports.upstreamHandleFromProxyOf = exports.upstreamHandleFromPreferredUsername = exports.upstreamHandleFromAutomatedActor = exports.upstreamHandleFromAlsoKnownAs = exports.upstreamHandleFromProfileField = exports.federatedUsernameFromUpstreamUrl = exports.parseUpstreamProfileUrl = exports.upstreamProfileUrl = exports.stripBridgeBoilerplate = exports.createBridgeRelabeller = exports.blueskyUsernameFromHandle = exports.BSKY_NETWORK_DOMAIN = exports.FEDERATION_NETWORKS = exports.INSTANCE_ACTOR_USERNAME = exports.normalizeActorUsername = exports.createUrlBuilders = exports.DEFAULT_SIGNED_CONTENT_TYPE = exports.HTTP_SIGNATURE_ALGORITHM = exports.verifyHttpSignature = exports.signRequest = void 0;
+exports.LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND = exports.AP_ACTOR_TYPES = exports.isApActorType = exports.accountKindForActor = exports.localActorTypeForAccountKind = exports.normalizeAlsoKnownAs = exports.createLocalActorBuilder = exports.createDomainPolicy = exports.extractActorUriFromActivityId = exports.isSameFederationHost = exports.canonicalFederationHost = exports.AP_CONTEXT = exports.readProxyDeclarations = exports.upstreamHandleFromProxyOf = exports.upstreamHandleFromPreferredUsername = exports.upstreamHandleFromAutomatedActor = exports.upstreamHandleFromAlsoKnownAs = exports.upstreamHandleFromProfileField = exports.federatedUsernameFromUpstreamUrl = exports.parseUpstreamProfileUrl = exports.upstreamProfileUrl = exports.stripBridgeBoilerplate = exports.createBridgeRelabeller = exports.blueskyUsernameFromHandle = exports.BSKY_NETWORK_DOMAIN = exports.FEDERATION_NETWORKS = exports.INSTANCE_ACTOR_USERNAME = exports.normalizeActorUsername = exports.createUrlBuilders = exports.DEFAULT_SIGNED_CONTENT_TYPE = exports.HTTP_SIGNATURE_ALGORITHM = exports.verifyHttpSignature = exports.signRequest = void 0;
 /**
  * HTTP Signatures (draft-cavage) — the pure sign/verify crypto every Oxy app's
  * ActivityPub federation shares. Private-key custody is injected; the key never
@@ -95,6 +95,7 @@ var actorObject_1 = require("./actorObject");
 Object.defineProperty(exports, "createLocalActorBuilder", { enumerable: true, get: function () { return actorObject_1.createLocalActorBuilder; } });
 Object.defineProperty(exports, "normalizeAlsoKnownAs", { enumerable: true, get: function () { return actorObject_1.normalizeAlsoKnownAs; } });
 Object.defineProperty(exports, "localActorTypeForAccountKind", { enumerable: true, get: function () { return actorObject_1.localActorTypeForAccountKind; } });
+Object.defineProperty(exports, "accountKindForActor", { enumerable: true, get: function () { return actorObject_1.accountKindForActor; } });
 Object.defineProperty(exports, "isApActorType", { enumerable: true, get: function () { return actorObject_1.isApActorType; } });
 Object.defineProperty(exports, "AP_ACTOR_TYPES", { enumerable: true, get: function () { return actorObject_1.AP_ACTOR_TYPES; } });
 Object.defineProperty(exports, "LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND", { enumerable: true, get: function () { return actorObject_1.LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND; } });

package/dist/esm/actorObject.js

@@ -39,7 +39,10 @@ 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.
+ * Oxy account kind → the AS2 actor type the fediverse is told about it — the
+ * ONE table both directions read: what Oxy announces for its own accounts here,
+ * and, through {@link accountKindForActor}, what it records a remote actor as.
+ * Changing how a kind federates is an edit to this table and nowhere else.
  *
  * `satisfies Record<AccountKind, LocalActorType>` is the load-bearing part: a
  * kind added to `@oxy.so/contracts` fails THIS build rather than silently
@@ -71,6 +74,8 @@ export function isApActorType(value) {
  *    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.
+ *  - **`community` → `Group`.** A forum its members post into and that
+ *    re-broadcasts them: exactly what Lemmy, Mbin and Friendica mean by `Group`.
  *
  * 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
@@ -85,6 +90,7 @@ export const LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND = {
     project: 'Organization',
     bot: 'Service',
     channel: 'Organization',
+    community: 'Group',
 };
 /**
  * The AS2 actor type for an Oxy account kind, defaulting to `Person`.
@@ -101,6 +107,49 @@ export const LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND = {
 export function localActorTypeForAccountKind(kind) {
     return isAccountKind(kind) ? LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND[kind] : 'Person';
 }
+/**
+ * The inverse of {@link LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND}, derived from it. Three
+ * kinds share `Organization`, so a type reads back as the FIRST kind the table
+ * lists for it (`Organization` → `organization`); nothing on the wire tells a
+ * remote project from a remote organization.
+ */
+const ACCOUNT_KIND_BY_LOCAL_ACTOR_TYPE = (() => {
+    const inverse = new Map();
+    for (const [kind, type] of Object.entries(LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND)) {
+        if (!inverse.has(type))
+            inverse.set(type, kind);
+    }
+    return inverse;
+})();
+/**
+ * AS2 actor types Oxy never announces but receives, and the announced type each
+ * is read as. `Application` is a non-human software actor — what `Service`
+ * already says, and half of Mastodon's own `bot?`.
+ */
+const INBOUND_ACTOR_TYPE_ALIASES = new Map([
+    ['Application', 'Service'],
+]);
+/**
+ * The kind a `Group` that only its moderators may post into is recorded as.
+ * Such a group forwards nobody: it PUBLISHES (a PeerTube video channel, a
+ * WordPress multi-author blog), which is what an Oxy channel is. The one
+ * inbound signal the table above has no column for.
+ */
+const MODERATED_GROUP_KIND = 'channel';
+/**
+ * The Oxy account kind a REMOTE actor is recorded as, read from the same table
+ * the local announcement uses ({@link LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND}). A type
+ * the table does not know (absent, misspelt, an extension type) is `personal`,
+ * the same default {@link localActorTypeForAccountKind} announces.
+ */
+export function accountKindForActor(actor) {
+    if (typeof actor.type !== 'string')
+        return 'personal';
+    const type = INBOUND_ACTOR_TYPE_ALIASES.get(actor.type) ?? actor.type;
+    if (type === LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND.community && actor.postingRestrictedToMods === true)
+        return MODERATED_GROUP_KIND;
+    return ACCOUNT_KIND_BY_LOCAL_ACTOR_TYPE.get(type) ?? 'personal';
+}
 /** Map common image extensions to a MIME type for an actor image `mediaType`. */
 const IMAGE_MEDIA_TYPE_BY_EXT = {
     png: 'image/png',

package/dist/esm/index.js

@@ -62,4 +62,4 @@ 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, normalizeAlsoKnownAs, localActorTypeForAccountKind, isApActorType, AP_ACTOR_TYPES, LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND, } from './actorObject.js';
+export { createLocalActorBuilder, normalizeAlsoKnownAs, localActorTypeForAccountKind, accountKindForActor, isApActorType, AP_ACTOR_TYPES, LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND, } from './actorObject.js';

package/dist/types/actorObject.d.ts

@@ -36,28 +36,29 @@ export declare function isApActorType(value: unknown): value is ApActorType;
 /**
  * The AS2 actor types this engine will announce for a LOCAL user actor.
  *
- * Narrower than AS2's five actor types, and narrow ON PURPOSE — the union names
- * what the builder can emit, so the two absences are documented decisions rather
- * than oversights. Both were checked against real receiving implementations
- * (mastodon `a3649295`, lemmy `4ce92433`, misskey `b95e4841`, peertube
- * `fe0da961`), not against the spec:
+ * Narrower than AS2's five actor types, and narrow ON PURPOSE. Both decisions
+ * were checked against real receiving implementations (mastodon `a3649295`,
+ * lemmy `4ce92433`, misskey `b95e4841`, peertube `fe0da961`), not against the
+ * spec:
  *
  *  - **`Application`** is the INSTANCE actor's type (see the actor router's
  *    `/ap/users/instance` branch), reserved by convention for the software
  *    itself. No account is the software.
- *  - **`Group`** is refused because in the deployed fediverse it is not read as
- *    "a collective of actors" but as a FORWARDING actor, and the two failure
- *    modes are concrete. Lemmy reclassifies a remote `Group` as a COMMUNITY:
- *    it is followable and the Follow is Accepted, so it looks like it worked,
- *    and then it never shows a single post — we emit no `Announce`, and our
- *    Notes do not resolve to a community. PeerTube is worse and louder: it
- *    REJECTS a `Group` actor outright unless it carries `attributedTo` naming a
- *    `Person`. An Oxy account authors its own posts and forwards nothing, so
- *    `Group` would advertise a protocol this engine does not implement.
+ *  - **`Group`** is announced ONLY for a `community`, because in the deployed
+ *    fediverse it is not read as "a collective of actors" but as a FORWARDING
+ *    actor. Lemmy reclassifies a remote `Group` as a community: followable, the
+ *    Follow is Accepted, and then it never shows a post unless the actor
+ *    `Announce`s its members' posts. PeerTube rejects a `Group` outright unless
+ *    it carries `attributedTo` naming a `Person`. An account that authors its
+ *    own posts (a project, a channel) must therefore never claim it; a community
+ *    is the one kind whose nature IS forwarding.
  */
-export type LocalActorType = Extract<ApActorType, 'Person' | 'Organization' | 'Service'>;
+export type LocalActorType = Extract<ApActorType, 'Person' | 'Organization' | 'Service' | 'Group'>;
 /**
- * Oxy account kind → the AS2 actor type the fediverse is told about it.
+ * Oxy account kind → the AS2 actor type the fediverse is told about it — the
+ * ONE table both directions read: what Oxy announces for its own accounts here,
+ * and, through {@link accountKindForActor}, what it records a remote actor as.
+ * Changing how a kind federates is an edit to this table and nowhere else.
  *
  * `satisfies Record<AccountKind, LocalActorType>` is the load-bearing part: a
  * kind added to `@oxy.so/contracts` fails THIS build rather than silently
@@ -89,6 +90,8 @@ export type LocalActorType = Extract<ApActorType, 'Person' | 'Organization' | 'S
  *    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.
+ *  - **`community` → `Group`.** A forum its members post into and that
+ *    re-broadcasts them: exactly what Lemmy, Mbin and Friendica mean by `Group`.
  *
  * 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
@@ -103,6 +106,7 @@ export declare const LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND: {
     readonly project: "Organization";
     readonly bot: "Service";
     readonly channel: "Organization";
+    readonly community: "Group";
 };
 /**
  * The AS2 actor type for an Oxy account kind, defaulting to `Person`.
@@ -117,6 +121,19 @@ export declare const LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND: {
  * existed.
  */
 export declare function localActorTypeForAccountKind(kind: unknown): LocalActorType;
+/** The fields of a remote actor document that decide its kind. */
+export interface ActorKindSignals {
+    type?: unknown;
+    /** Lemmy's and PeerTube's flag: only moderators may post into this `Group`. */
+    postingRestrictedToMods?: unknown;
+}
+/**
+ * The Oxy account kind a REMOTE actor is recorded as, read from the same table
+ * the local announcement uses ({@link LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND}). A type
+ * the table does not know (absent, misspelt, an extension type) is `personal`,
+ * the same default {@link localActorTypeForAccountKind} announces.
+ */
+export declare function accountKindForActor(actor: ActorKindSignals): AccountKind;
 /**
  * App-supplied media resolution for the actor `icon`/`image`. Each function
  * resolves a stored reference (Oxy file id or URL) to a FINAL, ready-to-serve

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, 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';
+export { createLocalActorBuilder, normalizeAlsoKnownAs, localActorTypeForAccountKind, accountKindForActor, type ActorKindSignals, 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, keyed by the transport a connector speaks.
  * `instagram-graph` is Meta's Graph API Business Discovery: a read-only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/federation",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "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",

package/src/__tests__/actorObject.test.ts

@@ -7,6 +7,7 @@ import {
   isApActorType,
   LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND,
   localActorTypeForAccountKind,
+  accountKindForActor,
   type ActorMediaResolver,
 } from '../index';
 
@@ -198,6 +199,7 @@ describe('actor type by Oxy account kind', () => {
     expect(localActorTypeForAccountKind('project')).toBe('Organization');
     expect(localActorTypeForAccountKind('bot')).toBe('Service');
     expect(localActorTypeForAccountKind('channel')).toBe('Organization');
+    expect(localActorTypeForAccountKind('community')).toBe('Group');
   });
 
   it('never announces a human-curated channel as automated', () => {
@@ -207,10 +209,11 @@ describe('actor type by Oxy account kind', () => {
     // A channel is curated by people; only `bot` may claim automation.
     expect(localActorTypeForAccountKind('channel')).not.toBe('Service');
     expect(localActorTypeForAccountKind('bot')).toBe('Service');
-    // `Group` is never emitted for anything: Lemmy would reclassify the actor as
-    // a community that silently never receives content, and PeerTube rejects a
-    // `Group` lacking `attributedTo` outright.
-    expect(Object.values(LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND)).not.toContain('Group');
+    // `Group` is announced for a community alone: Lemmy reads it as a forwarding
+    // community, and PeerTube rejects a `Group` lacking `attributedTo` outright.
+    expect(ACCOUNT_KINDS.filter((kind) => localActorTypeForAccountKind(kind) === 'Group')).toEqual([
+      'community',
+    ]);
   });
 
   it('covers every account kind contracts defines, with more than one answer', () => {
@@ -219,13 +222,30 @@ describe('actor type by Oxy account kind', () => {
     // Vacuity floor: a mapping that returned one constant would pass every
     // single-kind assertion above and fail this.
     const answers = ACCOUNT_KINDS.map((kind) => localActorTypeForAccountKind(kind));
-    expect(new Set(answers).size).toBe(3);
+    expect(new Set(answers).size).toBe(4);
     // And specifically: the two kinds either side of the channel decision differ.
     expect(localActorTypeForAccountKind('channel')).not.toBe(
       localActorTypeForAccountKind('personal'),
     );
   });
 
+  it('reads every announced type back as a kind announced the same way', () => {
+    for (const kind of ACCOUNT_KINDS) {
+      const type = localActorTypeForAccountKind(kind);
+      expect(localActorTypeForAccountKind(accountKindForActor({ type }))).toBe(type);
+    }
+  });
+
+  it('reads the actor types and flags Oxy never announces', () => {
+    expect(accountKindForActor({ type: 'Application' })).toBe('bot');
+    expect(accountKindForActor({ type: 'Group', postingRestrictedToMods: true })).toBe('channel');
+    expect(accountKindForActor({ type: 'Group', postingRestrictedToMods: false })).toBe(
+      'community',
+    );
+    expect(accountKindForActor({ type: 'Tombstone' })).toBe('personal');
+    expect(accountKindForActor({})).toBe('personal');
+  });
+
   it('falls back to Person for an absent, null, or unrecognized kind', () => {
     expect(localActorTypeForAccountKind(undefined)).toBe('Person');
     expect(localActorTypeForAccountKind(null)).toBe('Person');

package/src/actorObject.ts

@@ -49,29 +49,30 @@ export function isApActorType(value: unknown): value is ApActorType {
 /**
  * The AS2 actor types this engine will announce for a LOCAL user actor.
  *
- * Narrower than AS2's five actor types, and narrow ON PURPOSE — the union names
- * what the builder can emit, so the two absences are documented decisions rather
- * than oversights. Both were checked against real receiving implementations
- * (mastodon `a3649295`, lemmy `4ce92433`, misskey `b95e4841`, peertube
- * `fe0da961`), not against the spec:
+ * Narrower than AS2's five actor types, and narrow ON PURPOSE. Both decisions
+ * were checked against real receiving implementations (mastodon `a3649295`,
+ * lemmy `4ce92433`, misskey `b95e4841`, peertube `fe0da961`), not against the
+ * spec:
  *
  *  - **`Application`** is the INSTANCE actor's type (see the actor router's
  *    `/ap/users/instance` branch), reserved by convention for the software
  *    itself. No account is the software.
- *  - **`Group`** is refused because in the deployed fediverse it is not read as
- *    "a collective of actors" but as a FORWARDING actor, and the two failure
- *    modes are concrete. Lemmy reclassifies a remote `Group` as a COMMUNITY:
- *    it is followable and the Follow is Accepted, so it looks like it worked,
- *    and then it never shows a single post — we emit no `Announce`, and our
- *    Notes do not resolve to a community. PeerTube is worse and louder: it
- *    REJECTS a `Group` actor outright unless it carries `attributedTo` naming a
- *    `Person`. An Oxy account authors its own posts and forwards nothing, so
- *    `Group` would advertise a protocol this engine does not implement.
+ *  - **`Group`** is announced ONLY for a `community`, because in the deployed
+ *    fediverse it is not read as "a collective of actors" but as a FORWARDING
+ *    actor. Lemmy reclassifies a remote `Group` as a community: followable, the
+ *    Follow is Accepted, and then it never shows a post unless the actor
+ *    `Announce`s its members' posts. PeerTube rejects a `Group` outright unless
+ *    it carries `attributedTo` naming a `Person`. An account that authors its
+ *    own posts (a project, a channel) must therefore never claim it; a community
+ *    is the one kind whose nature IS forwarding.
  */
-export type LocalActorType = Extract<ApActorType, 'Person' | 'Organization' | 'Service'>;
+export type LocalActorType = Extract<ApActorType, 'Person' | 'Organization' | 'Service' | 'Group'>;
 
 /**
- * Oxy account kind → the AS2 actor type the fediverse is told about it.
+ * Oxy account kind → the AS2 actor type the fediverse is told about it — the
+ * ONE table both directions read: what Oxy announces for its own accounts here,
+ * and, through {@link accountKindForActor}, what it records a remote actor as.
+ * Changing how a kind federates is an edit to this table and nowhere else.
  *
  * `satisfies Record<AccountKind, LocalActorType>` is the load-bearing part: a
  * kind added to `@oxy.so/contracts` fails THIS build rather than silently
@@ -103,6 +104,8 @@ export type LocalActorType = Extract<ApActorType, 'Person' | 'Organization' | 'S
  *    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.
+ *  - **`community` → `Group`.** A forum its members post into and that
+ *    re-broadcasts them: exactly what Lemmy, Mbin and Friendica mean by `Group`.
  *
  * 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
@@ -117,6 +120,7 @@ export const LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND = {
   project: 'Organization',
   bot: 'Service',
   channel: 'Organization',
+  community: 'Group',
 } as const satisfies Record<AccountKind, LocalActorType>;
 
 /**
@@ -135,6 +139,58 @@ export function localActorTypeForAccountKind(kind: unknown): LocalActorType {
   return isAccountKind(kind) ? LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND[kind] : 'Person';
 }
 
+/**
+ * The inverse of {@link LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND}, derived from it. Three
+ * kinds share `Organization`, so a type reads back as the FIRST kind the table
+ * lists for it (`Organization` → `organization`); nothing on the wire tells a
+ * remote project from a remote organization.
+ */
+const ACCOUNT_KIND_BY_LOCAL_ACTOR_TYPE: ReadonlyMap<string, AccountKind> = (() => {
+  const inverse = new Map<string, AccountKind>();
+  for (const [kind, type] of Object.entries(LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND)) {
+    if (!inverse.has(type)) inverse.set(type, kind as AccountKind);
+  }
+  return inverse;
+})();
+
+/**
+ * AS2 actor types Oxy never announces but receives, and the announced type each
+ * is read as. `Application` is a non-human software actor — what `Service`
+ * already says, and half of Mastodon's own `bot?`.
+ */
+const INBOUND_ACTOR_TYPE_ALIASES: ReadonlyMap<string, LocalActorType> = new Map([
+  ['Application', 'Service'],
+]);
+
+/**
+ * The kind a `Group` that only its moderators may post into is recorded as.
+ * Such a group forwards nobody: it PUBLISHES (a PeerTube video channel, a
+ * WordPress multi-author blog), which is what an Oxy channel is. The one
+ * inbound signal the table above has no column for.
+ */
+const MODERATED_GROUP_KIND: AccountKind = 'channel';
+
+/** The fields of a remote actor document that decide its kind. */
+export interface ActorKindSignals {
+  type?: unknown;
+  /** Lemmy's and PeerTube's flag: only moderators may post into this `Group`. */
+  postingRestrictedToMods?: unknown;
+}
+
+/**
+ * The Oxy account kind a REMOTE actor is recorded as, read from the same table
+ * the local announcement uses ({@link LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND}). A type
+ * the table does not know (absent, misspelt, an extension type) is `personal`,
+ * the same default {@link localActorTypeForAccountKind} announces.
+ */
+export function accountKindForActor(actor: ActorKindSignals): AccountKind {
+  if (typeof actor.type !== 'string') return 'personal';
+  const type = INBOUND_ACTOR_TYPE_ALIASES.get(actor.type) ?? actor.type;
+  if (type === LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND.community && actor.postingRestrictedToMods === true)
+    return MODERATED_GROUP_KIND;
+  return ACCOUNT_KIND_BY_LOCAL_ACTOR_TYPE.get(type) ?? 'personal';
+}
+
 /** Map common image extensions to a MIME type for an actor image `mediaType`. */
 const IMAGE_MEDIA_TYPE_BY_EXT: Record<string, string> = {
   png: 'image/png',

package/src/index.ts

@@ -119,6 +119,8 @@ export {
   createLocalActorBuilder,
   normalizeAlsoKnownAs,
   localActorTypeForAccountKind,
+  accountKindForActor,
+  type ActorKindSignals,
   isApActorType,
   AP_ACTOR_TYPES,
   LOCAL_ACTOR_TYPE_BY_ACCOUNT_KIND,