@oxyhq/contracts 0.19.0 → 0.21.0

package/dist/esm/deviceSession.js

@@ -97,3 +97,64 @@ export const sessionAccountsChangedEventSchema = z.object({
     revision: z.number().int().nonnegative(),
     reason: sessionAccountsChangedReasonSchema,
 });
+/* -------------------------------------------------------------------------- */
+/*  Background credential — native background code with no JS runtime         */
+/* -------------------------------------------------------------------------- */
+/**
+ * Response from `POST /session/device/background-credential` — provisioned by
+ * the SDK WHILE THE APP IS RUNNING (bearer required, `deviceId` and account
+ * derived server-side from it) and consumed afterwards only by native
+ * background code, which has no JS runtime to mint a token for itself.
+ *
+ * Deliberately a SEPARATE credential from the rotating `deviceSecret`: that one
+ * rotates on every mint, so background code presenting it would become a second
+ * writer of a value the JS runtime depends on, and background code killed
+ * mid-rotation would silently sign the user out on the next cold start. Against
+ * this credential background code is the sole writer, and it can never rotate
+ * anything JS reads.
+ *
+ * The raw `secret` is returned exactly once, at provision time — never stored
+ * retrievably, never logged, never re-read. A caller that loses it provisions
+ * a new one.
+ *
+ * `expiresAt` is an unvalidated string, like every other expiry in this file:
+ * no consumer on the JS path interprets it (native background code parses it
+ * itself), and a `.datetime()` here alone would leave one strict field beside
+ * two lax ones. If expiry is ever validated it goes on all three at once, with
+ * the API's serializers checked against it — the producer is the same server.
+ */
+export const deviceBackgroundCredentialResponseSchema = z.object({
+    deviceId: z.string().min(1),
+    secret: z.string().min(1),
+    accountId: z.string().min(1),
+    expiresAt: z.string(),
+});
+/**
+ * Request body for `POST /session/device/background-token` — presented by
+ * native background code with NO bearer and NO cookies: possession of the
+ * background `secret` IS the proof, as it is for the device-secret mint.
+ *
+ * Unlike that mint this one NEVER rotates the presented secret (hence no
+ * `next…` field to persist in the response), so background code interrupted
+ * anywhere between request and response leaves the credential intact and
+ * usable on its next run.
+ */
+export const deviceBackgroundTokenRequestSchema = z.object({
+    deviceId: z.string().min(1),
+    secret: z.string().min(1),
+});
+/**
+ * Wire shape of a successful `POST /session/device/background-token`: the short
+ * access token, its expiry, and the account the token belongs to — the last so
+ * a caller can key cached data per account and drop data belonging to a
+ * foreign one.
+ *
+ * Carries NO device state — no account list, no `activeAccountId`, no
+ * `revision`, unlike {@link deviceTokenMintResponseSchema} — deliberately, to
+ * cap what a compromised credential record yields.
+ */
+export const deviceBackgroundTokenResponseSchema = z.object({
+    accessToken: z.string(),
+    expiresAt: z.string(),
+    accountId: z.string().min(1),
+});

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';
@@ -42,9 +43,33 @@ publicCardSchema, signedPublicCardSchema, realLifeAttestationRecordSchema, realL
 // Verifiable Credentials (Fase 4 — NEW)
 credentialRecordSchema, verifiableCredentialResponseSchema, credentialIssueResultSchema, credentialListResultSchema, credentialVerifyResultSchema, } from './civic.js';
 export { 
+// Closed value sets — shared by the API's mongoose enums, the API's request
+// validation, and the SDK's unions, so a new category/tier/status cannot be
+// added on one side only.
+REPUTATION_CATEGORIES, REPUTATION_TRANSACTION_STATUSES, TRUST_TIERS, REPUTATION_TARGET_ENTITY_TYPES, REPUTATION_DISPUTE_STATUSES, REPUTATION_INFLUENCE_CONTEXTS, 
+// Schemas — closed value sets
+reputationCategorySchema, reputationTransactionStatusSchema, trustTierSchema, reputationTargetEntityTypeSchema, reputationDisputeStatusSchema, reputationInfluenceContextSchema, 
+// Schemas — responses
+reputationTransactionSchema, reputationBalanceBreakdownSchema, reputationInfluenceSchema, reputationReliabilitySchema, reputationBalanceSummarySchema, reputationBalanceSchema, reputationDisputeSchema, reputationRuleSchema, reputationLeaderboardUserSchema, reputationLeaderboardEntrySchema, reputationInfluenceResultSchema, reverseReputationTransactionResultSchema, 
+// Schemas — request bodies
+awardReputationSchema, createReputationDisputeSchema, resolveReputationDisputeSchema, upsertReputationRuleSchema, reverseReputationTransactionSchema, 
+// 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, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedReasonSchema, sessionAccountsChangedEventSchema, } from './deviceSession.js';
+export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, deviceBackgroundCredentialResponseSchema, deviceBackgroundTokenRequestSchema, deviceBackgroundTokenResponseSchema, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedReasonSchema, sessionAccountsChangedEventSchema, } from './deviceSession.js';
 export { 
 // Schemas
 loginResultSchema, } from './deviceBoot.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(),
+});