@oxy.so/contracts 1.0.0

package/dist/esm/reputation.js

@@ -0,0 +1,293 @@
+/**
+ * Oxy Trust — reputation API contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the reputation ledger's wire shapes: the closed
+ * value sets (`REPUTATION_CATEGORIES`, `TRUST_TIERS`, …), the response entities
+ * (`ReputationTransaction`, the two balance views, `ReputationDispute`,
+ * `ReputationRule`, the leaderboard entry) and the request bodies the write
+ * endpoints accept. The API validates its OUTPUT against these schemas and its
+ * INPUT with the same request schemas the SDK's input types are derived from;
+ * `@oxy.so/core`'s reputation mixin imports every type from here rather than
+ * declaring its own.
+ *
+ * Why this module exists: the balance endpoint was view-split server-side
+ * without the SDK type moving with it, and for hours the SDK affirmatively
+ * type-checked a read of `balance.reliability.reportAccuracyScore` against a
+ * response that no longer carried `reliability`. Nothing structural connected
+ * the API's hand-written serializers (which returned `Record<string, unknown>`)
+ * to the SDK's interfaces — only human attention. With the serializers
+ * annotated against these definitions, that divergence is a build failure.
+ *
+ * Design anchors:
+ *  - **Ids are strings, timestamps are ISO 8601 strings.** The server holds
+ *    `ObjectId`s and `Date`s; every serializer converts at the boundary, so a
+ *    `Date` leaking into a field this module types as `string` fails to compile.
+ *  - **The balance has two views, and the union is the contract.** See
+ *    {@link ReputationBalanceView} — the compile-time assertions below are what
+ *    stop the private view's fields becoming reachable on a stranger's balance.
+ *  - **The closed value sets live here, not beside the mongoose models.** The
+ *    API's model enums and the SDK's unions are the same `as const` tuple, so a
+ *    seventh category cannot be added on one side only.
+ *
+ * The response entities are declared as explicit `interface`s with their runtime
+ * schemas annotated `z.ZodType<Interface>`, following `./links` and
+ * `./userResponse`: a `z.infer<>` of a nested-object schema can degrade to `{}`
+ * under a consumer's `moduleResolution: "node"` (node10) resolution, while a
+ * literal interface emits the field types verbatim in the `.d.ts` and survives
+ * both `node` and `bundler`.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+import { userNameSchema } from './userResponse.js';
+import { reputationConductSchema, reputationContextualInfluenceSchema, reputationContributionSchema, reputationPersonhoodSchema, reputationReportingSchema, reputationReviewingSchema, } from './moderationReputation.js';
+/* -------------------------------------------------------------------------- */
+/*  Closed value sets                                                         */
+/* -------------------------------------------------------------------------- */
+/**
+ * Category bucket a reputation transaction falls into. Drives the per-category
+ * balance breakdown; every rule and transaction carries exactly one.
+ *
+ * - `content`    — posts, comments, media a user authored.
+ * - `social`     — follows, likes, social interactions.
+ * - `trust`      — identity / verification / trust-graph signals.
+ * - `moderation` — reports filed, moderation actions, review outcomes.
+ * - `physical`   — real-world signals (event check-ins, verified purchases).
+ * - `penalty`    — negative adjustments for abuse / policy violations.
+ * - `other`      — anything that does not fit the buckets above.
+ */
+export const REPUTATION_CATEGORIES = [
+    'content',
+    'social',
+    'trust',
+    'moderation',
+    'physical',
+    'penalty',
+    'other',
+];
+export const reputationCategorySchema = z.enum(REPUTATION_CATEGORIES);
+/**
+ * Transaction lifecycle status.
+ *
+ * - `active`   — counts toward the balance.
+ * - `disputed` — under dispute; still counts until the dispute resolves.
+ * - `reversed` — superseded by a compensating reversal transaction; excluded.
+ * - `voided`   — administratively excluded with no compensating entry.
+ */
+export const REPUTATION_TRANSACTION_STATUSES = [
+    'active',
+    'disputed',
+    'reversed',
+    'voided',
+];
+export const reputationTransactionStatusSchema = z.enum(REPUTATION_TRANSACTION_STATUSES);
+/**
+ * Trust tiers, lowest → highest trust, plus the punitive `restricted`.
+ *
+ * Publicly visible: this is the contribution ladder the reputation system
+ * exists to publish. Note it doubles as the sanction marker — a `restricted`
+ * account is publicly identifiable as such.
+ */
+export const TRUST_TIERS = ['restricted', 'new', 'trusted', 'high_trust', 'verified'];
+export const trustTierSchema = z.enum(TRUST_TIERS);
+/** Kind of entity a transaction may target. */
+export const REPUTATION_TARGET_ENTITY_TYPES = [
+    'post',
+    'comment',
+    'report',
+    'purchase',
+    'event',
+    'check_in',
+    'manual_review',
+    'user',
+    'other',
+];
+export const reputationTargetEntityTypeSchema = z.enum(REPUTATION_TARGET_ENTITY_TYPES);
+/** Dispute lifecycle status. */
+export const REPUTATION_DISPUTE_STATUSES = [
+    'open',
+    'accepted',
+    'rejected',
+    'needs_review',
+];
+export const reputationDisputeStatusSchema = z.enum(REPUTATION_DISPUTE_STATUSES);
+/** Influence context selecting which capped weight axis to read. */
+export const REPUTATION_INFLUENCE_CONTEXTS = [
+    'default',
+    'report',
+    'moderation',
+    'ranking',
+];
+export const reputationInfluenceContextSchema = z.enum(REPUTATION_INFLUENCE_CONTEXTS);
+export const reputationTransactionSchema = z.object({
+    id: z.string(),
+    userId: z.string(),
+    points: z.number(),
+    actionType: z.string(),
+    category: reputationCategorySchema,
+    applicationId: z.string().optional(),
+    credentialId: z.string().optional(),
+    sourceActionId: z.string().optional(),
+    sourceActionType: z.string().optional(),
+    targetEntityId: z.string().optional(),
+    targetEntityType: reputationTargetEntityTypeSchema.optional(),
+    status: reputationTransactionStatusSchema,
+    reversedTransactionId: z.string().optional(),
+    reason: z.string().optional(),
+    metadata: z.record(z.unknown()).optional(),
+    createdByUserId: z.string().optional(),
+    reviewedByUserId: z.string().optional(),
+    reviewedAt: z.string().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const reputationBalanceBreakdownSchema = z.object({
+    content: z.number(),
+    social: z.number(),
+    trust: z.number(),
+    moderation: z.number(),
+    physical: z.number(),
+    penalties: z.number(),
+});
+export const reputationInfluenceSchema = z.object({
+    defaultWeight: z.number(),
+    reportWeight: z.number(),
+    moderationWeight: z.number(),
+    rankingFeedbackWeight: z.number(),
+});
+export const reputationReliabilitySchema = z.object({
+    accurateReports: z.number(),
+    rejectedReports: z.number(),
+    reportAccuracyScore: z.number(),
+    abuseScore: z.number(),
+});
+/** The fields both balance views share. Kept as a shape so the full view can spread it. */
+const balanceSummaryShape = {
+    userId: z.string(),
+    total: z.number(),
+    trustTier: trustTierSchema,
+};
+export const reputationBalanceSummarySchema = z.object(balanceSummaryShape);
+export const reputationBalanceSchema = z.object({
+    ...balanceSummaryShape,
+    positive: z.number(),
+    negative: z.number(),
+    breakdown: reputationBalanceBreakdownSchema,
+    influence: reputationInfluenceSchema,
+    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(),
+});
+/**
+ * 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',
+    'negative',
+    'breakdown',
+    'influence',
+    'reliability',
+    'recalculatedAt',
+    'updatedAt',
+];
+/**
+ * Whether a balance came back as the SUBJECT view, and so carries the
+ * breakdown / influence / reliability blocks.
+ *
+ * Checks every extra field rather than one representative: the point of the
+ * guard is that the caller then dereferences those blocks, so a partial payload
+ * must not narrow.
+ *
+ * @param balance - A balance from `getReputationBalance`.
+ */
+export function isFullReputationBalance(balance) {
+    return FULL_BALANCE_FIELDS.every((field) => field in balance);
+}
+export const reputationDisputeSchema = z.object({
+    id: z.string(),
+    transactionId: z.string(),
+    userId: z.string(),
+    reason: z.string(),
+    status: reputationDisputeStatusSchema,
+    evidence: z.array(z.string()).optional(),
+    resolvedAt: z.string().optional(),
+    resolvedByUserId: z.string().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const reputationRuleSchema = z.object({
+    id: z.string(),
+    actionType: z.string(),
+    points: z.number(),
+    category: reputationCategorySchema,
+    description: z.string(),
+    cooldownInMinutes: z.number(),
+    isEnabled: z.boolean(),
+});
+export const reputationLeaderboardUserSchema = z.object({
+    id: z.string(),
+    username: z.string(),
+    name: userNameSchema,
+    avatar: z.string().optional(),
+    publicKey: z.string().optional(),
+});
+export const reputationLeaderboardEntrySchema = z.object({
+    user: reputationLeaderboardUserSchema,
+    total: z.number(),
+    trustTier: trustTierSchema,
+    rank: z.number(),
+});
+export const reputationInfluenceResultSchema = z.object({
+    context: reputationInfluenceContextSchema,
+    weight: z.number(),
+    influence: reputationInfluenceSchema,
+});
+export const reverseReputationTransactionResultSchema = z.object({
+    original: reputationTransactionSchema,
+    reversal: reputationTransactionSchema,
+});
+export const awardReputationSchema = z.object({
+    userId: z.string().trim().min(1),
+    actionType: z.string().trim().min(1),
+    applicationId: z.string().trim().min(1).optional(),
+    credentialId: z.string().trim().min(1).optional(),
+    sourceActionId: z.string().trim().min(1).optional(),
+    sourceActionType: z.string().trim().min(1).optional(),
+    targetEntityId: z.string().trim().min(1).optional(),
+    targetEntityType: reputationTargetEntityTypeSchema.optional(),
+    reason: z.string().trim().max(500).optional(),
+    metadata: z.record(z.unknown()).optional(),
+});
+export const createReputationDisputeSchema = z.object({
+    transactionId: z.string().trim().min(1),
+    reason: z.string().trim().min(1).max(1000),
+    evidence: z.array(z.string().trim().min(1)).max(20).optional(),
+});
+export const resolveReputationDisputeSchema = z.object({
+    status: z.enum(['accepted', 'rejected']),
+});
+export const upsertReputationRuleSchema = z.object({
+    actionType: z.string().trim().min(1),
+    points: z.number(),
+    category: reputationCategorySchema,
+    description: z.string().trim().min(1).max(500),
+    cooldownInMinutes: z.number().int().min(0).default(0),
+    isEnabled: z.boolean().default(true),
+});
+export const reverseReputationTransactionSchema = z.object({
+    reason: z.string().trim().max(500).optional(),
+});

package/dist/esm/sessionStatus.js

@@ -0,0 +1,118 @@
+/**
+ * Canonical contract for `GET /auth/session/status/:sessionToken`.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the cross-app device-flow
+ * session-status payload and the sanitized public application identity it
+ * embeds. The API validates its OUTPUT against these schemas; the auth app
+ * (consent UI) validates its INPUT against the same schemas. Because there is
+ * exactly one definition, the producer and the consumer cannot drift.
+ *
+ * The class of bug that motivated moving this into `@oxy.so/contracts`: the auth
+ * app's LOCAL `sessionStatusSchema` typed `sessionId` as a non-nullable
+ * `z.string().optional()`. The producer emits `sessionId: authorizedSessionId ||
+ * null`, so a PENDING session (not yet authorized) carries `sessionId: null` —
+ * `.optional()` permits `undefined`/missing but REJECTS `null`, so `safeParse`
+ * failed, the whole response collapsed to `null`, and the consent screen showed
+ * "Unable to identify the requesting application". Pinning the nullability in one
+ * shared place makes that drift impossible.
+ *
+ * Faithful to the producers:
+ *  - `packages/api/src/utils/serializeApplication.ts` `serializePublicApplication`
+ *    — the ONLY shape returned to an unauthenticated consent UI. Optional fields
+ *    (`description`, `icon`, `websiteUrl`, `privacyPolicyUrl`, `termsUrl`,
+ *    `developerName`) are OMITTED when absent (never serialized as `null`), so
+ *    they are `.optional()` — NOT `.nullable()`. `type` is the `Application.type`
+ *    enum.
+ *  - `packages/api/src/routes/auth.ts` `GET /session/status/:sessionToken` — the
+ *    inner object of the API's `{ data: ... }` success envelope. The handler
+ *    ALWAYS emits `status`, `authorized` (`status === 'authorized'`),
+ *    `sessionToken`, `expiresAt` (ISO string), and `application` (resolved object
+ *    OR `null`). It ALWAYS emits `sessionId` / `publicKey` / `userId`, each as a
+ *    string value OR `null` (`authorizedSessionId || null`, `authorizedBy ||
+ *    null`, `authorizedUserId?.toString() || null`).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/**
+ * Application `type` enum. Mirrors `APPLICATION_TYPES` in
+ * `packages/api/src/models/Application.ts` (`first_party` | `third_party` |
+ * `internal` | `system`).
+ */
+export const applicationTypeSchema = z.enum([
+    'first_party',
+    'third_party',
+    'internal',
+    'system',
+]);
+/**
+ * The display-safe public identity of a requesting application, exactly as
+ * `serializePublicApplication` emits it. Returned by the API inside
+ * `GET /auth/session/status/:sessionToken` (device flow) and
+ * `GET /auth/oauth/client/:clientId` (OAuth code flow).
+ *
+ * Optional fields are `.optional()` (NOT `.nullable()`): the serializer OMITS
+ * `description` / `icon` / `websiteUrl` / `privacyPolicyUrl` / `termsUrl` /
+ * `developerName` when the underlying value is absent — it never writes `null`
+ * for them. `developerName` is only attached for non-official apps when a name
+ * could be resolved.
+ */
+export const publicApplicationSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().optional(),
+    icon: z.string().optional(),
+    websiteUrl: z.string().optional(),
+    privacyPolicyUrl: z.string().optional(),
+    termsUrl: z.string().optional(),
+    type: applicationTypeSchema,
+    isOfficial: z.boolean(),
+    isInternal: z.boolean(),
+    scopes: z.array(z.string()),
+    developerName: z.string().optional(),
+});
+/**
+ * The inner object of `GET /auth/session/status/:sessionToken` (inside the API's
+ * `{ data: ... }` envelope).
+ *
+ * `application` is the resolved {@link publicApplicationSchema} identity of the
+ * requesting application, or `null` when the bound app was hard-deleted / is no
+ * longer `active` (defensive — normally always present).
+ *
+ * `sessionId` / `publicKey` / `userId` are `.nullable().optional()`: the producer
+ * ALWAYS emits the key, with a string for an AUTHORIZED session or `null` for a
+ * PENDING one. `.nullable()` accepts the PENDING `null`; `.optional()` is belt-
+ * and-braces so a consumer is never broken by a future projection that drops the
+ * key. (`.optional()` alone would REJECT the PENDING `null` — that was the bug.)
+ *
+ * `authorized` / `sessionToken` / `expiresAt` are emitted unconditionally by the
+ * current producer and are never `null`, but stay `.optional()` so the contract
+ * tolerates leaner shapes from other producers of this same payload without a
+ * coordinated bump.
+ *
+ * `pushSentAt` / `openedAt` are DELIVERY PROGRESS, not authorization state: they
+ * let a waiting surface render "Check Commons on your phone" → "Opened in
+ * Commons" without inventing competing statuses. `status` remains the only
+ * authority on whether the request is pending, authorized, cancelled or expired.
+ * Both are `.nullable().optional()` for the same reason as `sessionId` — the
+ * producer always emits the key with `null` until that step happens, and an
+ * older API that omits them entirely must degrade, not fail the parse.
+ */
+export const sessionStatusSchema = z.object({
+    status: z.string(),
+    authorized: z.boolean().optional(),
+    sessionToken: z.string().optional(),
+    application: publicApplicationSchema.nullable().optional(),
+    expiresAt: z.string().optional(),
+    sessionId: z.string().nullable().optional(),
+    publicKey: z.string().nullable().optional(),
+    userId: z.string().nullable().optional(),
+    /**
+     * What approving this request does. Legacy rows read as `device_sign_in`.
+     * OAuth-bound sessions finalize into an authorization code (no `sessionId`).
+     */
+    purpose: z.enum(['device_sign_in', 'oauth_authorization']).optional(),
+    pushSentAt: z.string().nullable().optional(),
+    openedAt: z.string().nullable().optional(),
+});

package/dist/esm/transparency.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+/**
+ * Transparency log — the public wire contract of the checkpoint surface.
+ *
+ * A checkpoint is the operator's signed commitment to EVERY subject's chain head
+ * at a point in time: "at `periodEnd` I committed to `root` over `treeSize`
+ * subjects, and the previous checkpoint hashed to `prevCheckpointHash`". Anyone
+ * can then ask for an inclusion proof of their own head and verify it against
+ * that root without trusting the server — which is what closes the one gap a
+ * per-subject hash chain cannot close on its own (the server serving two
+ * different histories, or quietly dropping a record).
+ *
+ * The Merkle math, the leaf/checkpoint signing bytes, and the proof verifier all
+ * live in `@oxy.so/protocol` (`src/transparency/`); this module only fixes the
+ * SHAPES that cross the wire, so a client and the API cannot drift on them.
+ *
+ * Digest fields are pinned to 64-char LOWERCASE hex on purpose: the digests are
+ * compared as strings against locally recomputed hashes, so accepting an
+ * upper-case or truncated variant would turn a real mismatch into a confusing
+ * verification failure at a distance.
+ */
+/** A SHA-256 digest in the exact form the protocol emits: 64 lowercase hex chars. */
+const hexDigestSchema = z.string().regex(/^[0-9a-f]{64}$/, 'Expected a 64-char lowercase hex digest');
+/**
+ * One signer's endorsement of a checkpoint's signed fields.
+ *
+ * The operator and every independent witness produce this same shape over the
+ * SAME bytes, so the array on a checkpoint can grow without coordination.
+ */
+export const transparencyCheckpointSignatureSchema = z.object({
+    /** Uncompressed hex public key of the signer. */
+    publicKey: z.string().min(1),
+    alg: z.literal('ES256K-DER-SHA256'),
+    /** DER-encoded hex secp256k1 signature over the checkpoint signing input. */
+    signature: z.string().min(1),
+});
+/** Where a checkpoint root was published on a public chain. */
+export const transparencyAnchorSchema = z.object({
+    /** Chain/network identifier, e.g. `faircoin-main`. */
+    network: z.string().min(1),
+    txid: z.string().min(1),
+    confirmations: z.number().int().nonnegative(),
+    /** When the anchoring transaction was broadcast (ms epoch). */
+    anchoredAt: z.number().int().positive(),
+});
+/**
+ * A published checkpoint.
+ *
+ * `signatures` is non-empty by contract: an unsigned root commits nobody and
+ * must never be served as a checkpoint. `anchors` may be empty — a checkpoint is
+ * published immediately and anchored asynchronously, so "not yet anchored" is a
+ * normal, temporary state rather than an error.
+ */
+export const transparencyCheckpointSchema = z.object({
+    index: z.number().int().nonnegative(),
+    /** End of the committed period (ms epoch). */
+    periodEnd: z.number().int().positive(),
+    /** Number of subjects (leaves) committed. */
+    treeSize: z.number().int().nonnegative(),
+    root: hexDigestSchema,
+    /** Hash of the previous checkpoint; `null` only at genesis. */
+    prevCheckpointHash: hexDigestSchema.nullable(),
+    signatures: z.array(transparencyCheckpointSignatureSchema).min(1),
+    anchors: z.array(transparencyAnchorSchema),
+});
+/**
+ * An inclusion proof for one subject against one checkpoint.
+ *
+ * Carries the leaf PREIMAGE (`subjectDid`, `seq`, `headRecordId`) as well as the
+ * `leaf` digest so the verifier re-derives the leaf itself rather than trusting
+ * the server's hash, then walks `proof` up to the checkpoint's `root`.
+ */
+export const transparencyInclusionProofSchema = z.object({
+    checkpoint: transparencyCheckpointSchema,
+    subjectDid: z.string().min(1),
+    seq: z.number().int().nonnegative(),
+    headRecordId: hexDigestSchema,
+    leaf: hexDigestSchema,
+    leafIndex: z.number().int().nonnegative(),
+    /** Audit path, leaf-adjacent sibling first; empty for a single-leaf tree. */
+    proof: z.array(hexDigestSchema),
+});
+/** A page of the checkpoint chain, oldest first, for walking `prevCheckpointHash`. */
+export const transparencyCheckpointListSchema = z.object({
+    checkpoints: z.array(transparencyCheckpointSchema),
+});