@oxy.so/contracts 1.0.0

package/dist/types/moderationReputation.d.ts

@@ -0,0 +1,487 @@
+/**
+ * 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';
+/**
+ * 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 declare const MODERATION_SEVERITIES: readonly ["low", "medium", "high", "critical"];
+export type ModerationSeverity = (typeof MODERATION_SEVERITIES)[number];
+export declare const moderationSeveritySchema: z.ZodEnum<["low", "medium", "high", "critical"]>;
+/**
+ * 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 declare const MODERATION_FINDING_SCOPES: readonly ["application_local", "oxy_network", "identity_integrity"];
+export type ModerationFindingScope = (typeof MODERATION_FINDING_SCOPES)[number];
+export declare const moderationFindingScopeSchema: z.ZodEnum<["application_local", "oxy_network", "identity_integrity"]>;
+/** Which participant in the reported material the finding attributes to. */
+export declare const MODERATION_ATTRIBUTIONS: readonly ["author", "sharer", "reporter", "reviewer"];
+export type ModerationAttribution = (typeof MODERATION_ATTRIBUTIONS)[number];
+export declare const moderationAttributionSchema: z.ZodEnum<["author", "sharer", "reporter", "reviewer"]>;
+/**
+ * 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 declare const MODERATION_DECISION_STATUSES: readonly ["provisional", "final", "inconclusive", "superseded", "corrected"];
+export type ModerationDecisionStatus = (typeof MODERATION_DECISION_STATUSES)[number];
+export declare const moderationDecisionStatusSchema: z.ZodEnum<["provisional", "final", "inconclusive", "superseded", "corrected"]>;
+/**
+ * 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 declare const MODERATION_EFFECT_TYPES: readonly ["conduct_penalty", "report_abuse_penalty", "review_abuse_penalty"];
+export type ModerationEffectType = (typeof MODERATION_EFFECT_TYPES)[number];
+export declare const moderationEffectTypeSchema: z.ZodEnum<["conduct_penalty", "report_abuse_penalty", "review_abuse_penalty"]>;
+/** Lifecycle of a stored effect. */
+export declare const MODERATION_EFFECT_STATUSES: readonly ["applied", "reversed"];
+export type ModerationEffectStatus = (typeof MODERATION_EFFECT_STATUSES)[number];
+export declare const moderationEffectStatusSchema: z.ZodEnum<["applied", "reversed"]>;
+/** Lifecycle of a conduct strike. Only `active` strikes carry active risk. */
+export declare const CONDUCT_STRIKE_STATUSES: readonly ["active", "expired", "reversed"];
+export type ConductStrikeStatus = (typeof CONDUCT_STRIKE_STATUSES)[number];
+export declare const conductStrikeStatusSchema: z.ZodEnum<["active", "expired", "reversed"]>;
+/**
+ * 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 declare const CONDUCT_STANDINGS: readonly ["good", "watch", "limited", "restricted"];
+export type ConductStanding = (typeof CONDUCT_STANDINGS)[number];
+export declare const conductStandingSchema: z.ZodEnum<["good", "watch", "limited", "restricted"]>;
+/** Contribution tier, derived from contribution points only. */
+export declare const CONTRIBUTION_TIERS: readonly ["new", "trusted", "high_trust"];
+export type ContributionTier = (typeof CONTRIBUTION_TIERS)[number];
+export declare const contributionTierSchema: z.ZodEnum<["new", "trusted", "high_trust"]>;
+/** Personhood status. Being a real person proves neither conduct nor competence. */
+export declare const PERSONHOOD_STATUSES: readonly ["unknown", "probable", "verified"];
+export type PersonhoodStatusValue = (typeof PERSONHOOD_STATUSES)[number];
+export declare const personhoodStatusSchema: z.ZodEnum<["unknown", "probable", "verified"]>;
+/**
+ * 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 declare const IDENTITY_BINDING_TYPES: readonly ["oauth_grant", "session_proof", "commons_signature", "federated_actor"];
+export type IdentityBindingType = (typeof IDENTITY_BINDING_TYPES)[number];
+export declare const identityBindingTypeSchema: z.ZodEnum<["oauth_grant", "session_proof", "commons_signature", "federated_actor"]>;
+/** Binding lifecycle. A revoked binding proves nothing about a later action. */
+export declare const IDENTITY_BINDING_STATUSES: readonly ["active", "revoked"];
+export type IdentityBindingStatus = (typeof IDENTITY_BINDING_STATUSES)[number];
+export declare const identityBindingStatusSchema: z.ZodEnum<["active", "revoked"]>;
+/**
+ * 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 declare const APPLICATION_MODERATION_STANDINGS: readonly ["sandbox", "trusted", "restricted"];
+export type ApplicationModerationStanding = (typeof APPLICATION_MODERATION_STANDINGS)[number];
+export declare const applicationModerationStandingSchema: z.ZodEnum<["sandbox", "trusted", "restricted"]>;
+/**
+ * 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 declare const MODERATION_EFFECT_SKIP_REASONS: readonly ["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 type ModerationEffectSkipReason = (typeof MODERATION_EFFECT_SKIP_REASONS)[number];
+export declare const moderationEffectSkipReasonSchema: z.ZodEnum<["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"]>;
+/** One finding of a published decision. */
+export interface ModerationFinding {
+    /** Taxonomy code, e.g. `harassment.targeted_abuse`. Never rendered publicly. */
+    code: string;
+    severity: ModerationSeverity;
+    scope: ModerationFindingScope;
+    attribution: ModerationAttribution;
+    /**
+     * Conduct family the code belongs to (e.g. `harassment`). Repetition is
+     * assessed per family and time window, so stacking taxonomy labels cannot
+     * manufacture a disproportionate sanction.
+     */
+    family: string;
+}
+export declare const moderationFindingSchema: z.ZodType<ModerationFinding>;
+/** The principal a decision is about, and the proof it is who the emitter says. */
+export interface ModerationDecisionEventSubject {
+    /** Only `oxy_user` can carry a global reputation effect today. */
+    principalType: 'oxy_user';
+    /** The Oxy user id (or publicKey) the emitter claims the actor resolves to. */
+    principalId: string;
+    /**
+     * The identity binding that proves it. REQUIRED — an event without a
+     * resolvable binding produces no effect, by construction rather than by
+     * policy.
+     */
+    bindingProofId: string;
+}
+export declare const moderationDecisionEventSubjectSchema: z.ZodType<ModerationDecisionEventSubject>;
+/**
+ * The policy versions a decision was made under. All three are recorded on the
+ * effect so a consequence stays explainable after any of them moves on.
+ */
+export interface ModerationPolicyVersions {
+    /** The universal taxonomy version. */
+    universal: string;
+    /** The application's own policy version. */
+    application: string;
+    /** The Oxy conduct policy version the consequence engine must resolve. */
+    oxyConduct: string;
+}
+export declare const moderationPolicyVersionsSchema: z.ZodType<ModerationPolicyVersions>;
+/**
+ * `POST /reputation/moderation/effects` — a decision a moderation service
+ * published, offered to Oxy Trust for consequence derivation.
+ *
+ * The emitter states a decision. It never states an effect: no points, no risk,
+ * no standing, no duration. Those are derived here from the policy version the
+ * decision names, which is what keeps the direction one-way.
+ */
+export interface ModerationDecisionEvent {
+    /** Emitter-unique event id. Replay of the same id is a no-op. */
+    eventId: string;
+    /**
+     * The application the reported action happened in — NOT the emitter.
+     *
+     * This is in the body, and the reason is worth stating because the sibling
+     * rule elsewhere is the opposite: at a moderation service's own ingress,
+     * `applicationId` must come from the credential, because a tenant choosing
+     * its own tenant id is an IDOR. Here the emitter is a privileged internal
+     * service reporting ON BEHALF OF an application, so it cannot be the
+     * credential's own id. What bounds it instead is that this field is checked
+     * against TWO independent gates the emitter does not control: the named
+     * application must itself be permitted to produce global effects, and the
+     * binding proof must be one the NAMED application holds for this person.
+     * Naming an application the subject never used therefore yields no effect.
+     */
+    reportedApplicationId: string;
+    /** Event type + version, e.g. `moderation.decision.finalized.v1`. */
+    type: string;
+    caseId: string;
+    /**
+     * The cross-tenant incident the case belongs to. THE unit of consequence:
+     * one incident yields one effect per (principal, effect type, revision).
+     */
+    incidentId: string;
+    decisionId: string;
+    /** 1-based revision. An appeal publishes revision 2, never edits revision 1. */
+    decisionRevision: number;
+    subject: ModerationDecisionEventSubject;
+    findings: ModerationFinding[];
+    decisionStatus: ModerationDecisionStatus;
+    policyVersions: ModerationPolicyVersions;
+    /**
+     * ISO 8601 time of the REPORTED ACTION (not of the decision). The binding
+     * must have existed at or before this instant, which is what makes the
+     * binding a proof of presence rather than an after-the-fact claim.
+     */
+    occurredAt: string;
+    /**
+     * Hash of the private decision document. Recorded on the effect and in the
+     * attestation so provenance is verifiable without the decision's contents.
+     */
+    proofHash: string;
+}
+export declare const moderationDecisionEventSchema: z.ZodType<ModerationDecisionEvent>;
+/**
+ * Which decision revision an operation addresses. Deliberately the whole body of
+ * `POST /reputation/moderation/effects/finalize`: confirming that a consequence
+ * landed must not be able to carry a figure, or it would become a second write
+ * path into the ledger.
+ */
+export interface FinalizeModerationDecisionInput {
+    decisionId: string;
+    decisionRevision: number;
+}
+export declare const finalizeModerationDecisionSchema: z.ZodType<FinalizeModerationDecisionInput>;
+/**
+ * `POST /reputation/moderation/effects/reverse` — an appeal overturned a
+ * decision revision, so the consequence it produced must be compensated.
+ *
+ * Names no figure either: the reversal is derived from the stored effect, so a
+ * caller cannot choose how much to give back.
+ */
+export interface ReverseModerationEffectInput extends FinalizeModerationDecisionInput {
+    /** Why the decision was overturned. Recorded on the reversal. */
+    reason: string;
+}
+export declare const reverseModerationEffectSchema: z.ZodType<ReverseModerationEffectInput>;
+/**
+ * What the engine derived for one principal from one decision revision.
+ *
+ * `points` and `activeRisk` are already multiplied and capped; the multipliers
+ * are reported so the figure is explainable without re-running the engine.
+ */
+export interface ModerationEffect {
+    /** The effect's own id (its Mongo `_id` as a string). */
+    id: string;
+    incidentId: string;
+    caseId: string;
+    decisionId: string;
+    decisionRevision: number;
+    /** The Oxy user the effect landed on. */
+    principalId: string;
+    effectType: ModerationEffectType;
+    status: ModerationEffectStatus;
+    /** Signed point delta written to the ledger (negative for a penalty). */
+    points: number;
+    /** Active-risk delta added to conduct standing. */
+    activeRisk: number;
+    severity: ModerationSeverity;
+    /** Repetition multiplier applied (1.0 for a first similar incident). */
+    repetitionMultiplier: number;
+    /** Multi-finding multiplier applied, capped by the policy. */
+    multiFindingMultiplier: number;
+    /** The idempotency key the ledger transaction was written under. */
+    idempotencyKey: string;
+    /** The ledger transaction this effect created. */
+    transactionId: string;
+    /** The conduct strike this effect created, when the effect carries risk. */
+    strikeId?: string;
+    /** The compensating transaction, once reversed. */
+    reversalTransactionId?: string;
+    policyVersions: ModerationPolicyVersions;
+    /** ISO 8601 timestamp the effect was applied at. */
+    appliedAt: string;
+    /** ISO 8601 timestamp the effect was reversed at, if reversed. */
+    reversedAt?: string;
+}
+export declare const moderationEffectSchema: z.ZodType<ModerationEffect>;
+/**
+ * The response to an event submission.
+ *
+ * `applied: false` with a `skipReason` is a SUCCESS: the event was accepted and
+ * durably recorded as producing no effect, so the emitter must not retry.
+ */
+export interface ApplyModerationDecisionResult {
+    /** Whether a consequence was derived. */
+    applied: boolean;
+    /** Present when `applied` is true. */
+    effect?: ModerationEffect;
+    /** Present when `applied` is false. */
+    skipReason?: ModerationEffectSkipReason;
+    /**
+     * True when this exact event (or an equivalent effect for the incident and
+     * revision) had already been processed, so nothing new was written.
+     */
+    idempotent: boolean;
+}
+export declare const applyModerationDecisionResultSchema: z.ZodType<ApplyModerationDecisionResult>;
+/** The response to a reversal. */
+export interface ReverseModerationEffectResult {
+    /** Every effect the decision revision produced, now `reversed`. */
+    reversed: ModerationEffect[];
+    /** True when the effects were already reversed and nothing new was written. */
+    idempotent: boolean;
+}
+export declare const reverseModerationEffectResultSchema: z.ZodType<ReverseModerationEffectResult>;
+/**
+ * `POST /reputation/moderation/bindings` — register the fact that an Oxy user
+ * was present in the calling application under a local principal id.
+ *
+ * The caller is a service credential AND must present the user's own Oxy access
+ * token in `userProofToken`: the binding is only as strong as the proof, and a
+ * body an application composes on its own is no proof at all. `applicationId`
+ * comes from the credential.
+ */
+export interface RegisterIdentityBindingInput {
+    /** The application's own id for this person. */
+    localPrincipalId: string;
+    /**
+     * The USER'S Oxy access token, proving they were signed in to the calling
+     * application. Verified server-side; its subject must be the bound user.
+     */
+    userProofToken: string;
+}
+export declare const registerIdentityBindingSchema: z.ZodType<RegisterIdentityBindingInput>;
+/**
+ * A registered binding, as returned to the application that registered it.
+ *
+ * Carries no proof material: the token is verified and discarded, never stored.
+ * `id` is what an event's `bindingProofId` references.
+ */
+export interface IdentityBinding {
+    id: string;
+    applicationId: string;
+    /** The bound Oxy user id. */
+    userId: string;
+    localPrincipalId: string;
+    bindingType: IdentityBindingType;
+    status: IdentityBindingStatus;
+    /** ISO 8601 timestamp the binding was verified at. */
+    verifiedAt: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+}
+export declare const identityBindingSchema: z.ZodType<IdentityBinding>;
+/**
+ * Personhood: whether Oxy believes this is a real, distinct person.
+ *
+ * Deliberately NOT a trust tier. Being a real person proves neither good
+ * conduct nor moderation competence, so it is its own axis and confers nothing
+ * on the others.
+ */
+export interface ReputationPersonhood {
+    status: PersonhoodStatusValue;
+    /** 0..1 confidence in that status. */
+    score: number;
+}
+export declare const reputationPersonhoodSchema: z.ZodType<ReputationPersonhood>;
+/**
+ * Contribution: what the person has built. Positive-only ladder.
+ *
+ * `points` EXCLUDES conduct penalties — they live on the conduct axis. Their
+ * ledger entries still count toward the legacy `total`, so the ledger stays
+ * honest, but they neither lower the contribution tier nor can be offset by it.
+ */
+export interface ReputationContribution {
+    points: number;
+    tier: ContributionTier;
+}
+export declare const reputationContributionSchema: z.ZodType<ReputationContribution>;
+/**
+ * Conduct: the standing that moderation outcomes move.
+ *
+ * `activeRisk` is the sum of risk carried by ACTIVE strikes; it decays as
+ * strikes expire and drops immediately when one is reversed. `standing` is
+ * derived from `activeRisk` alone, which is precisely why contribution points
+ * cannot buy it back.
+ */
+export interface ReputationConduct {
+    standing: ConductStanding;
+    activeRisk: number;
+    activeStrikes: number;
+    /**
+     * ISO 8601 timestamp the earliest-expiring active strike lapses at. Absent
+     * when there is no active strike, or when every one of them requires manual
+     * recovery review (critical severity never expires automatically).
+     */
+    nextExpiryAt?: string;
+}
+export declare const reputationConductSchema: z.ZodType<ReputationConduct>;
+/**
+ * Reporting: how reliable this person's reports are.
+ *
+ * A Beta-posterior mean with a neutral prior, plus a confidence that grows with
+ * sample size — one accurate report does not make a perfect reporter, and a
+ * newcomer keeps a neutral prior. `malicious` counts CONFIRMED report abuse,
+ * and nothing else: a rejected report is not bad faith.
+ */
+export interface ReputationReporting {
+    /** Smoothed 0..1 accuracy estimate. */
+    reliability: number;
+    /** 0..1 confidence in that estimate, from effective sample size. */
+    confidence: number;
+    confirmed: number;
+    rejected: number;
+    /** Confirmed report-abuse findings. */
+    malicious: number;
+}
+export declare const reputationReportingSchema: z.ZodType<ReputationReporting>;
+/**
+ * Reviewing: how reliable this person is AS A REVIEWER, per category and
+ * language rather than as one global number — competence in one category says
+ * little about another.
+ */
+export interface ReputationReviewing {
+    globalReliability: number;
+    categoryReliability: Record<string, number>;
+    languageReliability: Record<string, number>;
+}
+export declare const reputationReviewingSchema: z.ZodType<ReputationReviewing>;
+/**
+ * The contextual influence weights the V2 model publishes.
+ *
+ * Separate from the legacy four-weight block: selection probability for a jury
+ * and the priority of a report are different questions, and neither is the
+ * weight of a vote. A vote is never weighted — one qualified person, one vote.
+ */
+export interface ReputationContextualInfluence {
+    reportPriorityWeight: number;
+    reviewSelectionWeight: number;
+    rankingWeight: number;
+}
+export declare const reputationContextualInfluenceSchema: z.ZodType<ReputationContextualInfluence>;
+/**
+ * An application's own moderation standing. A new application moderates
+ * locally from `sandbox` and produces no global effect until it has passed
+ * technical review and a sufficient quality period.
+ */
+export interface ApplicationModerationTrust {
+    applicationId: string;
+    standing: ApplicationModerationStanding;
+    /** 0..1 — how well the application's evidence survives scrutiny. */
+    evidenceIntegrity: number;
+    /** 0..1 — how well its identity bindings hold up. */
+    identityBindingReliability: number;
+    /** 0..1 — share of its decisions overturned on appeal. */
+    decisionOverturnRate: number;
+    /** 0..1 — assessed quality of its own policy. */
+    policyQuality: number;
+    /**
+     * THE gate. False for every application until explicitly granted, so the
+     * default for a newly-integrated application is local enforcement only.
+     */
+    globalReputationEffectsAllowed: boolean;
+}
+export declare const applicationModerationTrustSchema: z.ZodType<ApplicationModerationTrust>;

package/dist/types/oauth.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+/**
+ * The two `/auth/oauth/*` responses the browser hub's edge layer reads.
+ *
+ * They existed on the wire long before this file — `GET /auth/oauth/consent`
+ * and `POST /auth/oauth/authorize` are the surface `auth.oxy.so` has always
+ * driven with a bearer. What is new (issue #937 Phase 5) is a SECOND consumer
+ * that is not the SPA: the IdP's edge layer runs both calls server-side so the
+ * device-wide bearer never enters the browser's script context. A shape read by
+ * two independently deployed consumers is a contract, so it is written down
+ * once here and validated on both sides rather than transcribed into the edge.
+ *
+ * These are NOT the RFC 6749 token/userinfo responses. Those two speak flat
+ * OAuth/OIDC on the wire and are the one place in the API that does not use the
+ * `{ data }` envelope; these two are ordinary internal API responses that happen
+ * to be about OAuth.
+ */
+/**
+ * Server-authoritative answer to "must this user be shown a consent screen".
+ *
+ * Discriminated on `consentRequired` so the two arms cannot be confused by a
+ * consumer that reads `reason` first: `trusted`/`granted` are reasons NOT to
+ * ask, `new`/`scope_changed` are reasons to ask, and a flat object would let a
+ * typo in one produce a plausible value of the other.
+ *
+ *  - `trusted`       — the application is first-party/internal/system/official
+ *                      by the REGISTRY's verdict (`isTrustedApplication`), and
+ *                      the request names no scope over the user's own follow
+ *                      graph. Never inferred from a hostname.
+ *  - `granted`       — a prior `AppGrant` already covers every requested scope.
+ *  - `scope_changed` — a prior grant exists and is missing one.
+ *  - `new`           — no prior grant.
+ *
+ * `userConsentScopes` names the scopes that FORCED the screen, so the consent UI
+ * can say which one it is asking about. Present only on the `true` arm, and only
+ * when such a scope exists — a trusted app asked for one is still asked.
+ */
+export declare const oauthConsentDecisionSchema: z.ZodDiscriminatedUnion<"consentRequired", [z.ZodObject<{
+    consentRequired: z.ZodLiteral<false>;
+    reason: z.ZodEnum<["trusted", "granted"]>;
+}, "strip", z.ZodTypeAny, {
+    reason: "trusted" | "granted";
+    consentRequired: false;
+}, {
+    reason: "trusted" | "granted";
+    consentRequired: false;
+}>, z.ZodObject<{
+    consentRequired: z.ZodLiteral<true>;
+    reason: z.ZodEnum<["new", "scope_changed"]>;
+    userConsentScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    reason: "new" | "scope_changed";
+    consentRequired: true;
+    userConsentScopes?: string[] | undefined;
+}, {
+    reason: "new" | "scope_changed";
+    consentRequired: true;
+    userConsentScopes?: string[] | undefined;
+}>]>;
+/**
+ * A minted authorization code.
+ *
+ * `state` is echoed back as the caller sent it and is `null` when they sent
+ * none — never omitted, so a consumer cannot read "the server dropped my state"
+ * as "I sent none". `redirectUri` is echoed for the same reason the code is
+ * bound to it server-side: the caller must be able to see that the value the
+ * code was issued against is the one it registered.
+ */
+export declare const oauthAuthorizeCodeResponseSchema: z.ZodObject<{
+    code: z.ZodString;
+    state: z.ZodNullable<z.ZodString>;
+    redirectUri: z.ZodString;
+    expiresIn: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    state: string | null;
+    redirectUri: string;
+    expiresIn: number;
+}, {
+    code: string;
+    state: string | null;
+    redirectUri: string;
+    expiresIn: number;
+}>;
+export type OauthConsentDecision = z.infer<typeof oauthConsentDecisionSchema>;
+export type OauthAuthorizeCodeResponse = z.infer<typeof oauthAuthorizeCodeResponseSchema>;

package/dist/types/oxyRecordTypes.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Oxy-scoped signed-record types.
+ *
+ * The base `signedRecordEnvelopeSchema` (`./identity`) treats `type` as an OPEN,
+ * non-empty string so ANY Oxy app may sign on the shared envelope grammar. The
+ * Oxy STORE re-narrows it to the closed set in this module — a `type` outside it
+ * is rejected as `invalid_envelope`.
+ *
+ * `oxySignedRecordTypeSchema` is that runtime gate (the API's `verifyEnvelope`
+ * re-narrows with it; the Mongoose `SignedRecord.type` enum and the Postgres
+ * CHECK on `signed_records.type` are both derived from `.options`);
+ * `OxySignedRecordType` is the matching compile-time union the SDK
+ * identity/civic mixins type against.
+ *
+ * The signing input INCLUDES `type`, so this set is part of the signed bytes —
+ * a record cannot have its category swapped after signing, and a value once
+ * signed can never be renamed.
+ *
+ * v1 only ever carried `identity` / `profile` (already in production); v2 added
+ * the civic record types (reputation attestations, real-life / peer validations,
+ * personhood vouches, verifiable credentials) and the user-node registration
+ * record.
+ *
+ * ## Why `app_record` is here, when it deliberately was not
+ *
+ * This set used to hold Oxy's own categories only, and said so: an app's `type`
+ * was "intentionally NOT in this set". The reason given was that the store
+ * accepts only what it knows how to **verify and materialize**. Verification
+ * turned out not to argue for the exclusion — the engine verifies a signature
+ * against the subject's keys whatever the category says — and materialization
+ * is the app's job, not the store's: an app projects its own feed tables from
+ * records it reads back.
+ *
+ * What changed is the decision the exclusion blocked. One chain per PERSON, held
+ * by Oxy, is the ecosystem substrate: apps append their records to the subject's
+ * one chain instead of each keeping a private chain for the same person. A
+ * closed set that admits no app category makes that unrepresentable.
+ *
+ * `app_record` is ONE value rather than an open lane, and the lexicon lives in
+ * the envelope's `collection` (`app.mention.feed.post`, `app.syra.*`), which the
+ * store denormalizes to `signed_records.nsid` and indexes. So a new app needs no
+ * change here — it picks its own collection namespace and signs `app_record`,
+ * exactly as Mention already does in production. Keeping the set closed is what
+ * keeps the CHECK a real constraint.
+ *
+ * **Admitting the category is not the whole of that decision.** Two gates sit
+ * beside it and are unchanged: an app record must arrive as a v2 (chained)
+ * envelope, and `oxyVerificationResolver` accepts exactly one custodial issuer
+ * (`OXY_DID`). So a record a user signs themselves verifies here today, while
+ * one an app signs custodially under its OWN issuer DID does not — that needs a
+ * separate, deliberate answer about which issuers may write to a person's chain.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo, ESM-safe.
+ */
+import { z } from 'zod';
+export declare const oxySignedRecordTypeSchema: z.ZodEnum<["identity", "profile", "reputation_attestation", "real_life_attestation", "validation_verdict", "personhood_vouch", "credential", "node", "app_record"]>;
+/**
+ * The closed set of record categories the Oxy identity/civic/node store accepts.
+ * The base envelope `type` is an open string; this is what the Oxy store
+ * re-narrows it to.
+ */
+export type OxySignedRecordType = z.infer<typeof oxySignedRecordTypeSchema>;