@oxyhq/contracts 0.20.0 → 0.21.0

package/dist/esm/index.js

@@ -24,6 +24,7 @@ export {
 // enum, and the SDK's `denyCommonsSignIn`.
 COMMONS_DENY_REASONS, commonsDenyReasonSchema, IDENTITY_APPROVAL_PUSH_CHANNEL, } from './commonsSignIn.js';
 export { INBOX_EMAIL_PUSH_CHANNEL, INBOX_EMAIL_PUSH_TYPE, inboxEmailPushDataSchema, } from './inboxPush.js';
+export { OXY_USER_INVALIDATION_CHANNEL, OXY_USER_CHANGE_REASONS, OXY_PUBLISHED_USER_CHANGE_REASONS, isPublishedOxyUserChangeReason, oxyUserInvalidationEventSchema, } from './userInvalidation.js';
 export { 
 // Schemas
 recommendationExcludeTypeSchema, recommendationBoostSchema, recommendationSignalWeightsSchema, recommendationRequestSchema, recommendationCountSchema, recommendationItemSchema, recommendationResponseSchema, appEndorsementInputSchema, appInterestInputSchema, appUserSignalIngestSchema, appAffinityEventTypeSchema, appAffinityEventSchema, appAffinityEventsIngestSchema, } from './recommendations.js';
@@ -55,6 +56,17 @@ awardReputationSchema, createReputationDisputeSchema, resolveReputationDisputeSc
 // Narrows the two balance views apart at runtime.
 isFullReputationBalance, } from './reputation.js';
 export { 
+// Closed value sets — the moderation reputation bridge (CrowdSource → Oxy Trust).
+MODERATION_SEVERITIES, MODERATION_FINDING_SCOPES, MODERATION_ATTRIBUTIONS, MODERATION_DECISION_STATUSES, MODERATION_EFFECT_TYPES, MODERATION_EFFECT_STATUSES, MODERATION_EFFECT_SKIP_REASONS, CONDUCT_STRIKE_STATUSES, CONDUCT_STANDINGS, CONTRIBUTION_TIERS, PERSONHOOD_STATUSES, IDENTITY_BINDING_TYPES, IDENTITY_BINDING_STATUSES, APPLICATION_MODERATION_STANDINGS, 
+// Schemas — closed value sets
+moderationSeveritySchema, moderationFindingScopeSchema, moderationAttributionSchema, moderationDecisionStatusSchema, moderationEffectTypeSchema, moderationEffectStatusSchema, moderationEffectSkipReasonSchema, conductStrikeStatusSchema, conductStandingSchema, contributionTierSchema, personhoodStatusSchema, identityBindingTypeSchema, identityBindingStatusSchema, applicationModerationStandingSchema, 
+// Schemas — the event and its receipt
+moderationFindingSchema, moderationDecisionEventSubjectSchema, moderationPolicyVersionsSchema, moderationDecisionEventSchema, finalizeModerationDecisionSchema, reverseModerationEffectSchema, moderationEffectSchema, applyModerationDecisionResultSchema, reverseModerationEffectResultSchema, 
+// Schemas — identity binding
+registerIdentityBindingSchema, identityBindingSchema, 
+// Schemas — the derived V2 axes
+reputationPersonhoodSchema, reputationContributionSchema, reputationConductSchema, reputationReportingSchema, reputationReviewingSchema, reputationContextualInfluenceSchema, applicationModerationTrustSchema, } from './moderationReputation.js';
+export { 
 // Schemas
 linkPreviewSchema, linkPreviewBatchRequestSchema, linkPreviewBatchResponseSchema, linkPreviewResponseSchema, } from './links.js';
 export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, deviceBackgroundCredentialResponseSchema, deviceBackgroundTokenRequestSchema, deviceBackgroundTokenResponseSchema, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedReasonSchema, sessionAccountsChangedEventSchema, } from './deviceSession.js';

package/dist/esm/moderationReputation.js

@@ -0,0 +1,295 @@
+/**
+ * Oxy Trust — the moderation reputation bridge (CrowdSource → Oxy Trust).
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shapes crossing the one-way boundary
+ * between a participatory-moderation service and the Oxy reputation ledger.
+ *
+ * The direction is not negotiable: a moderation service NEVER writes reputation.
+ * It emits an authenticated internal event describing a decision it published,
+ * and Oxy's own consequence engine validates that event and derives the effect.
+ * Everything in this module is therefore either (a) the event, (b) the receipt
+ * the engine returns, or (c) the derived state the engine publishes back to the
+ * subject.
+ *
+ * Design anchors, all load-bearing:
+ *
+ *  - **Conduct is a separate axis from contribution.** A conduct penalty raises
+ *    `activeRisk` and creates a strike; positive contribution points can never
+ *    cancel a strike, because standing is derived from active risk and not from
+ *    the point total. See {@link ReputationConduct}.
+ *  - **The reporting axis carries only reporting signals.** `abuseScore` on the
+ *    legacy reliability block conflated rejected reports with every negative
+ *    transaction; {@link ReputationReporting} exists so a conduct penalty can
+ *    never inflate a report-abuse figure.
+ *  - **No binding proof, no effect.** {@link ModerationDecisionEventSubject}
+ *    requires a `bindingProofId`, and the engine rejects an event whose binding
+ *    does not resolve to the claimed principal at or before `occurredAt`. An
+ *    application cannot move a reputation figure by naming a user id.
+ *  - **One penalty per incident.** The idempotency key is
+ *    `moderation:<incidentId>:<decisionRevision>:<effectType>`; a hundred
+ *    reports about the same material produce one effect.
+ *  - **Every effect carries the policy version it was decided under**, so a
+ *    consequence can be recomputed under the original policy rather than under
+ *    whatever the current tuning happens to be.
+ *
+ * Platform-agnostic — zod only. ESM-safe (no `require()`).
+ */
+import { z } from 'zod';
+/* -------------------------------------------------------------------------- */
+/*  Closed value sets                                                         */
+/* -------------------------------------------------------------------------- */
+/**
+ * Severity band of a moderation finding, lowest → highest.
+ *
+ * The band — not the taxonomy code — is what the consequence engine consumes:
+ * points, active risk and expiry are all keyed by severity in the versioned
+ * conduct policy, so a new taxonomy code needs no engine change and no
+ * intimate category ever reaches the ledger.
+ */
+export const MODERATION_SEVERITIES = ['low', 'medium', 'high', 'critical'];
+export const moderationSeveritySchema = z.enum(MODERATION_SEVERITIES);
+/**
+ * How far a finding reaches.
+ *
+ * - `application_local`   — the application enforces locally; Oxy Trust is NOT
+ *   touched. Emitted for completeness; the engine rejects the effect.
+ * - `oxy_network`         — conduct against the Oxy network as a whole.
+ * - `identity_integrity`  — impersonation, sybil behaviour, credential abuse.
+ *
+ * Only `oxy_network` and `identity_integrity` can produce a global effect.
+ */
+export const MODERATION_FINDING_SCOPES = [
+    'application_local',
+    'oxy_network',
+    'identity_integrity',
+];
+export const moderationFindingScopeSchema = z.enum(MODERATION_FINDING_SCOPES);
+/** Which participant in the reported material the finding attributes to. */
+export const MODERATION_ATTRIBUTIONS = ['author', 'sharer', 'reporter', 'reviewer'];
+export const moderationAttributionSchema = z.enum(MODERATION_ATTRIBUTIONS);
+/**
+ * Lifecycle of the decision the event describes.
+ *
+ * `inconclusive` is its own outcome and never collapses into "no violation";
+ * it simply produces no effect. `superseded` and `corrected` describe a
+ * revision that a later one replaced — an event in either state is rejected,
+ * because applying it would resurrect a consequence the appeal removed.
+ */
+export const MODERATION_DECISION_STATUSES = [
+    'provisional',
+    'final',
+    'inconclusive',
+    'superseded',
+    'corrected',
+];
+export const moderationDecisionStatusSchema = z.enum(MODERATION_DECISION_STATUSES);
+/**
+ * The kind of consequence an effect carries. Each is its own axis, and the
+ * idempotency key includes it — one incident may legitimately produce a conduct
+ * effect for the author AND a report-abuse effect for a malicious reporter.
+ */
+export const MODERATION_EFFECT_TYPES = [
+    'conduct_penalty',
+    'report_abuse_penalty',
+    'review_abuse_penalty',
+];
+export const moderationEffectTypeSchema = z.enum(MODERATION_EFFECT_TYPES);
+/** Lifecycle of a stored effect. */
+export const MODERATION_EFFECT_STATUSES = ['applied', 'reversed'];
+export const moderationEffectStatusSchema = z.enum(MODERATION_EFFECT_STATUSES);
+/** Lifecycle of a conduct strike. Only `active` strikes carry active risk. */
+export const CONDUCT_STRIKE_STATUSES = ['active', 'expired', 'reversed'];
+export const conductStrikeStatusSchema = z.enum(CONDUCT_STRIKE_STATUSES);
+/**
+ * Conduct standing, derived from ACTIVE RISK and nothing else.
+ *
+ * Deliberately independent of the point total: a person may hold a high
+ * contribution tier and a `limited` standing at the same time, and earning
+ * points cannot move standing back toward `good`. Only expiry or reversal can.
+ */
+export const CONDUCT_STANDINGS = ['good', 'watch', 'limited', 'restricted'];
+export const conductStandingSchema = z.enum(CONDUCT_STANDINGS);
+/** Contribution tier, derived from contribution points only. */
+export const CONTRIBUTION_TIERS = ['new', 'trusted', 'high_trust'];
+export const contributionTierSchema = z.enum(CONTRIBUTION_TIERS);
+/** Personhood status. Being a real person proves neither conduct nor competence. */
+export const PERSONHOOD_STATUSES = ['unknown', 'probable', 'verified'];
+export const personhoodStatusSchema = z.enum(PERSONHOOD_STATUSES);
+/**
+ * How an Oxy identity was bound to the actor an application reported.
+ *
+ * - `oauth_grant`        — the user authorized the application through Oxy's own
+ *   OAuth flow. Oxy wrote the record; the application asserts nothing.
+ * - `session_proof`      — the application presented the USER'S OWN Oxy access
+ *   token alongside its service credential, proving the user was present in
+ *   that application under a named local principal id.
+ * - `commons_signature`  — a DID-verifiable signature over a server-issued nonce.
+ * - `federated_actor`    — a resolvable, authorized federated actor link.
+ */
+export const IDENTITY_BINDING_TYPES = [
+    'oauth_grant',
+    'session_proof',
+    'commons_signature',
+    'federated_actor',
+];
+export const identityBindingTypeSchema = z.enum(IDENTITY_BINDING_TYPES);
+/** Binding lifecycle. A revoked binding proves nothing about a later action. */
+export const IDENTITY_BINDING_STATUSES = ['active', 'revoked'];
+export const identityBindingStatusSchema = z.enum(IDENTITY_BINDING_STATUSES);
+/**
+ * An application's own moderation standing. An external application can abuse
+ * the system too, so it carries standing exactly like a person does.
+ *
+ * `sandbox` applications moderate locally and produce NO global effect.
+ */
+export const APPLICATION_MODERATION_STANDINGS = ['sandbox', 'trusted', 'restricted'];
+export const applicationModerationStandingSchema = z.enum(APPLICATION_MODERATION_STANDINGS);
+/**
+ * Why the engine declined to apply an effect.
+ *
+ * Returned rather than thrown for the cases that are a legitimate outcome of a
+ * well-formed event (a sandboxed application, a local-only finding, an
+ * inconclusive decision): the emitter must be able to record "delivered, no
+ * effect" and stop retrying. Malformed or unauthorized events are HTTP errors,
+ * not skip reasons.
+ */
+export const MODERATION_EFFECT_SKIP_REASONS = [
+    'no_binding_proof',
+    'binding_after_action',
+    'binding_principal_mismatch',
+    'binding_revoked',
+    'decision_not_effective',
+    'decision_superseded',
+    'finding_scope_local',
+    'finding_not_in_policy',
+    'application_not_permitted',
+    'no_effective_finding',
+];
+export const moderationEffectSkipReasonSchema = z.enum(MODERATION_EFFECT_SKIP_REASONS);
+export const moderationFindingSchema = z.object({
+    code: z.string().trim().min(1).max(200),
+    severity: moderationSeveritySchema,
+    scope: moderationFindingScopeSchema,
+    attribution: moderationAttributionSchema,
+    family: z.string().trim().min(1).max(100),
+});
+export const moderationDecisionEventSubjectSchema = z.object({
+    principalType: z.literal('oxy_user'),
+    principalId: z.string().trim().min(1),
+    bindingProofId: z.string().trim().min(1),
+});
+export const moderationPolicyVersionsSchema = z.object({
+    universal: z.string().trim().min(1).max(100),
+    application: z.string().trim().min(1).max(100),
+    oxyConduct: z.string().trim().min(1).max(100),
+});
+export const moderationDecisionEventSchema = z.object({
+    eventId: z.string().trim().min(1).max(200),
+    reportedApplicationId: z.string().trim().min(1).max(200),
+    type: z.string().trim().min(1).max(200),
+    caseId: z.string().trim().min(1).max(200),
+    incidentId: z.string().trim().min(1).max(200),
+    decisionId: z.string().trim().min(1).max(200),
+    decisionRevision: z.number().int().min(1),
+    subject: moderationDecisionEventSubjectSchema,
+    findings: z.array(moderationFindingSchema).min(1).max(20),
+    decisionStatus: moderationDecisionStatusSchema,
+    policyVersions: moderationPolicyVersionsSchema,
+    occurredAt: z.string().trim().min(1),
+    proofHash: z.string().trim().min(1).max(200),
+});
+export const finalizeModerationDecisionSchema = z.object({
+    decisionId: z.string().trim().min(1).max(200),
+    decisionRevision: z.number().int().min(1),
+});
+export const reverseModerationEffectSchema = z.object({
+    decisionId: z.string().trim().min(1).max(200),
+    decisionRevision: z.number().int().min(1),
+    reason: z.string().trim().min(1).max(500),
+});
+export const moderationEffectSchema = z.object({
+    id: z.string(),
+    incidentId: z.string(),
+    caseId: z.string(),
+    decisionId: z.string(),
+    decisionRevision: z.number(),
+    principalId: z.string(),
+    effectType: moderationEffectTypeSchema,
+    status: moderationEffectStatusSchema,
+    points: z.number(),
+    activeRisk: z.number(),
+    severity: moderationSeveritySchema,
+    repetitionMultiplier: z.number(),
+    multiFindingMultiplier: z.number(),
+    idempotencyKey: z.string(),
+    transactionId: z.string(),
+    strikeId: z.string().optional(),
+    reversalTransactionId: z.string().optional(),
+    policyVersions: moderationPolicyVersionsSchema,
+    appliedAt: z.string(),
+    reversedAt: z.string().optional(),
+});
+export const applyModerationDecisionResultSchema = z.object({
+    applied: z.boolean(),
+    effect: moderationEffectSchema.optional(),
+    skipReason: moderationEffectSkipReasonSchema.optional(),
+    idempotent: z.boolean(),
+});
+export const reverseModerationEffectResultSchema = z.object({
+    reversed: z.array(moderationEffectSchema),
+    idempotent: z.boolean(),
+});
+export const registerIdentityBindingSchema = z.object({
+    localPrincipalId: z.string().trim().min(1).max(200),
+    userProofToken: z.string().trim().min(1),
+});
+export const identityBindingSchema = z.object({
+    id: z.string(),
+    applicationId: z.string(),
+    userId: z.string(),
+    localPrincipalId: z.string(),
+    bindingType: identityBindingTypeSchema,
+    status: identityBindingStatusSchema,
+    verifiedAt: z.string(),
+    createdAt: z.string(),
+});
+export const reputationPersonhoodSchema = z.object({
+    status: personhoodStatusSchema,
+    score: z.number(),
+});
+export const reputationContributionSchema = z.object({
+    points: z.number(),
+    tier: contributionTierSchema,
+});
+export const reputationConductSchema = z.object({
+    standing: conductStandingSchema,
+    activeRisk: z.number(),
+    activeStrikes: z.number(),
+    nextExpiryAt: z.string().optional(),
+});
+export const reputationReportingSchema = z.object({
+    reliability: z.number(),
+    confidence: z.number(),
+    confirmed: z.number(),
+    rejected: z.number(),
+    malicious: z.number(),
+});
+export const reputationReviewingSchema = z.object({
+    globalReliability: z.number(),
+    categoryReliability: z.record(z.number()),
+    languageReliability: z.record(z.number()),
+});
+export const reputationContextualInfluenceSchema = z.object({
+    reportPriorityWeight: z.number(),
+    reviewSelectionWeight: z.number(),
+    rankingWeight: z.number(),
+});
+export const applicationModerationTrustSchema = z.object({
+    applicationId: z.string(),
+    standing: applicationModerationStandingSchema,
+    evidenceIntegrity: z.number(),
+    identityBindingReliability: z.number(),
+    decisionOverturnRate: z.number(),
+    policyQuality: z.number(),
+    globalReputationEffectsAllowed: z.boolean(),
+});

package/dist/esm/reputation.js

@@ -41,6 +41,7 @@
  */
 import { z } from 'zod';
 import { userNameSchema } from './userResponse.js';
+import { reputationConductSchema, reputationContextualInfluenceSchema, reputationContributionSchema, reputationPersonhoodSchema, reputationReportingSchema, reputationReviewingSchema, } from './moderationReputation.js';
 /* -------------------------------------------------------------------------- */
 /*  Closed value sets                                                         */
 /* -------------------------------------------------------------------------- */
@@ -177,11 +178,22 @@ export const reputationBalanceSchema = z.object({
     reliability: reputationReliabilitySchema,
     recalculatedAt: z.string(),
     updatedAt: z.string(),
+    personhood: reputationPersonhoodSchema.optional(),
+    contribution: reputationContributionSchema.optional(),
+    conduct: reputationConductSchema.optional(),
+    reporting: reputationReportingSchema.optional(),
+    reviewing: reputationReviewingSchema.optional(),
+    contextualInfluence: reputationContextualInfluenceSchema.optional(),
 });
 /**
- * Every field the full {@link ReputationBalance} carries beyond the public
- * {@link ReputationBalanceSummary}. The runtime discriminant between the two
- * views — the API sends this set all-or-nothing.
+ * The fields the full {@link ReputationBalance} carries beyond the public
+ * {@link ReputationBalanceSummary} that the API sends ALL-OR-NOTHING. The
+ * runtime discriminant between the two views.
+ *
+ * The V2 blocks (`conduct`, `contribution`, …) are deliberately NOT listed:
+ * they are optional on the wire, so requiring them here would make a balance
+ * from a server that predates them fail to narrow, hiding the whole private
+ * view. Read a V2 block by checking that block.
  */
 const FULL_BALANCE_FIELDS = [
     'positive',

package/dist/esm/userInvalidation.js

@@ -0,0 +1,85 @@
+/**
+ * Canonical contract for the Oxy user-invalidation broadcast.
+ *
+ * Oxy owns identity, but consumers cache it: Mention keeps a Redis summary per
+ * post author, and every backend using `@oxyhq/core` holds the SDK's own GET
+ * response cache. Both go stale the moment a profile is edited, and neither has
+ * any way to find out — the writer is a different process in a different repo.
+ * This is the signal that tells them.
+ *
+ * The channel name and the payload shape are wire contracts between oxy-api (the
+ * publisher) and every consuming backend (the subscribers), so they live here
+ * rather than in either side. A hand-typed copy of the channel name fails as
+ * "the invalidation never arrives" — silently, because pub/sub has no delivery
+ * receipt and a message nobody is listening for is indistinguishable from a
+ * message nobody sent.
+ *
+ * DELIVERY IS AT-MOST-ONCE, AND THAT IS THE DESIGN. Every consumer's cache still
+ * carries its own TTL, so a dropped message degrades to exactly the behaviour
+ * before this signal existed and never to something worse. That property is what
+ * makes a bare Redis PUBLISH sufficient here and an outbox, retries, delivery
+ * receipts and payload signatures unnecessary. Do not treat a received event as
+ * authoritative for anything except "re-read this user from Oxy".
+ *
+ * PRIVACY — the payload carries NO user data, only an id, a reason and a
+ * timestamp. The channel rides the shared Valkey that every Oxy backend can
+ * subscribe to, so anything placed on it is readable by every service in the
+ * ecosystem. Never add a name, handle, email, avatar or any profile field: a
+ * subscriber that wants the new values re-reads them from Oxy through its normal
+ * authenticated path, where the usual authorization applies.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo.
+ */
+import { z } from 'zod';
+/** Redis pub/sub channel carrying user-invalidation events. */
+export const OXY_USER_INVALIDATION_CHANNEL = 'oxy:user:invalidate';
+/**
+ * Why a user record changed, as classified by the writer in oxy-api.
+ *
+ * - `profile` — anything a consumer renders or caches as IDENTITY: display name,
+ *   username, avatar, bio, verification, federation fields, account status. This
+ *   is the DEFAULT for every writer, so a site that forgets to classify itself
+ *   over-invalidates (correct, marginally slower) rather than under-invalidates
+ *   (silently wrong). Keep that asymmetry if you add a reason.
+ * - `graph` — follow-edge churn only (follower/following counts). High frequency,
+ *   and bulk follow/unfollow moves up to 200 edges in one call. Nothing renders
+ *   identity from it and a stale count is harmless to ranking, so it is NOT
+ *   broadcast — see {@link OXY_PUBLISHED_USER_CHANGE_REASONS}.
+ */
+export const OXY_USER_CHANGE_REASONS = ['profile', 'graph'];
+/**
+ * The reasons that are actually put on the wire.
+ *
+ * A reason absent from this list is a local cache eviction in oxy-api and
+ * nothing more: no message is published at all, rather than a message every
+ * subscriber receives and discards. The distinction matters at bulk-follow
+ * scale, where the discarded variant is a 200-message burst on a channel every
+ * Oxy backend is subscribed to.
+ *
+ * This is deliberately a shared list rather than a check inside the publisher:
+ * a subscriber needs to know what it can receive, and the schema below rejects
+ * anything else, so publisher and subscriber cannot drift into disagreeing about
+ * which events exist. Adding a reason therefore forces an explicit decision about
+ * whether it broadcasts.
+ */
+export const OXY_PUBLISHED_USER_CHANGE_REASONS = ['profile'];
+/** Whether a change of this kind is broadcast to consumers at all. */
+export function isPublishedOxyUserChangeReason(reason) {
+    return OXY_PUBLISHED_USER_CHANGE_REASONS.includes(reason);
+}
+/**
+ * A single user-invalidation event.
+ *
+ * `at` is the publisher's epoch-ms clock, carried for diagnosis (measuring
+ * end-to-end propagation, spotting a wedged subscriber) — never for ordering or
+ * conflict resolution. Two Oxy tasks publish from unsynchronised clocks, and the
+ * event says only "re-read this user", which is idempotent and order-independent.
+ */
+export const oxyUserInvalidationEventSchema = z.object({
+    /** The Oxy user whose record changed. */
+    userId: z.string().min(1),
+    /** Why it changed. Only broadcast reasons appear on the wire. */
+    reason: z.enum(OXY_PUBLISHED_USER_CHANGE_REASONS),
+    /** Publisher's epoch-ms timestamp. Diagnostic only. */
+    at: z.number().int().nonnegative(),
+});