@oxy.so/contracts 1.0.0

package/dist/types/civic.d.ts

@@ -0,0 +1,338 @@
+/**
+ * Civic / Commons API contracts (Fase 1 — DNI + crypto-owned reputation).
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the public "DNI" card a Commons
+ * user shows (and others scan): the user's DID, display identity, trust tier,
+ * personhood status, verified domains, and credential badges — sealed with an
+ * Oxy custodial attestation so a scanner can verify it OFFLINE against the Oxy
+ * public key (the same `ES256K-DER-SHA256` scheme as the signed data export).
+ *
+ * The QR encodes ONLY the DID (`oxydni://card?did=…`) — never trust data — so a
+ * card cannot be spoofed by crafting a QR; the scanner resolves the signed card
+ * server-side and verifies the Oxy signature. The attestation is computed over
+ * the canonical-JSON of the `card` object, so a consumer re-canonicalizes the
+ * card it received and verifies `attestation.signature` against
+ * `attestation.publicKey` (which MUST be a current verification method of the
+ * Oxy DID).
+ *
+ * Explicit-`interface` exports (PublicCard, SignedPublicCard) follow the same
+ * node-resolution rationale as `UserNameResponse` / the identity contracts: a
+ * nested `z.infer<>` can degrade to `{}` under a consumer's
+ * `moduleResolution: "node"`, so the load-bearing shapes are declared as literal
+ * interfaces and the runtime schemas are annotated `z.ZodType<Interface>`.
+ *
+ * The `attestation` reuses the export-bundle `ExportAttestation` shape from
+ * `./identity` (mirrored, not duplicated): `{ issuer, publicKey, alg, signature,
+ * signedAt }`. It is `null` ONLY when the Oxy signing key is unconfigured (dev).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo, ESM-safe.
+ */
+import { z } from 'zod';
+import { type ExportAttestation } from './identity';
+/**
+ * The trust tier shown on the card. Mirrors the API's reputation `TRUST_TIERS`
+ * (lowest → highest, plus the punitive `restricted`). Declared as a literal
+ * union here (NOT imported from the API) so the contract package stays
+ * dependency-free while giving consumers an exhaustive type to render against.
+ */
+export type CardTrustTier = 'restricted' | 'new' | 'trusted' | 'high_trust' | 'verified';
+/**
+ * Personhood verification status. `unverified` for everyone in Fase 1; the
+ * web-of-trust pipeline (Fase 3) graduates users to `pending` / `verified`.
+ */
+export type PersonhoodStatus = 'unverified' | 'pending' | 'verified';
+/**
+ * The public, render-ready "DNI" card for a Commons user. Assembled server-side
+ * from the canonical account fields and signed by Oxy.
+ *
+ * - `name` is the canonical composed display name (`name.displayName`) — a
+ *   consumer renders it directly and NEVER recomposes it from `name.first` etc.
+ * - `username` / `avatarUrl` are OPTIONAL (omitted entirely for accounts that
+ *   have none) — `avatarUrl` is the public `cloud.oxy.so` URL when an avatar is
+ *   set. The server emits ONLY present keys so a consumer re-canonicalizing the
+ *   card it received derives byte-identical bytes for signature verification.
+ * - `trustTier` is the user's current reputation tier; `personhoodStatus` is
+ *   `unverified` for everyone in Fase 1 (Fase 3 graduates users) and
+ *   `credentialBadges` is `[]` until verifiable credentials land (Fase 4).
+ * - `issuedAt` is epoch milliseconds — part of the signed bytes (the attestation
+ *   covers the canonical-JSON of the whole card), so a scanner can detect a
+ *   stale/replayed card.
+ */
+export interface PublicCard {
+    did: string;
+    userId: string;
+    name: string;
+    username?: string;
+    avatarUrl?: string;
+    trustTier: CardTrustTier;
+    personhoodStatus: PersonhoodStatus;
+    verifiedDomains: string[];
+    credentialBadges: string[];
+    issuedAt: number;
+}
+export declare const publicCardSchema: z.ZodType<PublicCard>;
+/**
+ * A {@link PublicCard} sealed with an Oxy custodial attestation. The attestation
+ * is an `ES256K-DER-SHA256` signature over the canonical-JSON of `card` (the
+ * exact `ExportAttestation` shape reused from the signed data export). It is
+ * `null` ONLY when the Oxy signing key (`OXY_PRIVATE_KEY`/`OXY_PUBLIC_KEY`) is
+ * unconfigured (dev / pre-prod) — in production it is always present. A consumer
+ * MUST check `attestation !== null` and that `attestation.publicKey` is the Oxy
+ * custodial key before trusting the card.
+ */
+export interface SignedPublicCard {
+    card: PublicCard;
+    attestation: ExportAttestation | null;
+}
+export declare const signedPublicCardSchema: z.ZodType<SignedPublicCard>;
+/**
+ * The `record` payload of a `real_life_attestation` signed envelope. The
+ * COUNTERPARTY (B) signs this with their OWN key as a self-issued v2 record on
+ * THEIR chain (`subject === issuer === B.did`); the subject being attested (A)
+ * is referenced by `about` (A's DID). The server resolves `about` → A's account
+ * and awards A the HIGH-weight `real_life_attested` points, recording B as the
+ * attestor (so B can be slashed if A's action is later found fraudulent).
+ *
+ * - `context` is an opaque interaction id from the QR (`oxydni://attest?ctx=…`).
+ * - `nonce` is the single-use replay guard from the QR; `exp` is its expiry
+ *   (epoch ms) — both are part of the signed bytes.
+ * - `geohash` (optional) is a coarse co-location proof; `biometricOk` (optional)
+ *   signals B's device biometric gate fired before signing (a support signal,
+ *   never sufficient alone).
+ */
+export interface RealLifeAttestationRecord {
+    about: string;
+    context: string;
+    nonce: string;
+    exp: number;
+    geohash?: string;
+    biometricOk?: boolean;
+}
+export declare const realLifeAttestationRecordSchema: z.ZodType<RealLifeAttestationRecord>;
+/**
+ * The result of `POST /civic/attestations` on success: the stored attestation
+ * record id (B's envelope), the subject + attestor account ids, and the points
+ * awarded to the subject.
+ */
+export interface RealLifeAttestationResult {
+    accepted: true;
+    recordId: string;
+    subjectUserId: string;
+    attestorUserId: string;
+    points: number;
+}
+export declare const realLifeAttestationResultSchema: z.ZodType<RealLifeAttestationResult>;
+/** A juror's verdict on a validation request. */
+export type ValidationVerdict = 'valid' | 'invalid' | 'abstain';
+/** The lifecycle status of a validation request. */
+export type ValidationRequestStatus = 'pending' | 'quorum_met' | 'validated' | 'rejected' | 'expired';
+/**
+ * The `record` payload of a `validation_verdict` signed envelope — a juror's
+ * SELF-ISSUED verdict, bound to the request id + the canonical payload hash (so
+ * a verdict cannot be replayed onto a different request or an altered payload).
+ */
+export interface ValidationVerdictRecord {
+    requestId: string;
+    payloadHash: string;
+    verdict: ValidationVerdict;
+}
+export declare const validationVerdictRecordSchema: z.ZodType<ValidationVerdictRecord>;
+/** Request body for opening a validation request (`POST /civic/validations`). */
+export declare const validationOpenRequestSchema: z.ZodObject<{
+    subjectUserId: z.ZodString;
+    actionType: z.ZodString;
+    sourceActionId: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    highValue: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    subjectUserId: string;
+    actionType: string;
+    sourceActionId: string;
+    payload: Record<string, unknown>;
+    highValue?: boolean | undefined;
+}, {
+    subjectUserId: string;
+    actionType: string;
+    sourceActionId: string;
+    payload: Record<string, unknown>;
+    highValue?: boolean | undefined;
+}>;
+export type ValidationOpenRequest = z.infer<typeof validationOpenRequestSchema>;
+/** The result of opening a validation request (`POST /civic/validations`). */
+export interface ValidationOpenResult {
+    requestId: string;
+    selectedValidatorCount: number;
+    expiresAt: string;
+}
+export declare const validationOpenResultSchema: z.ZodType<ValidationOpenResult>;
+/**
+ * A pending validation request as shown in a juror's inbox. `payload` is the
+ * claim the juror inspects; `payloadHash` is what their verdict must bind to.
+ */
+export interface ValidationRequestSummary {
+    id: string;
+    subjectUserId: string;
+    actionType: string;
+    payload: Record<string, unknown>;
+    payloadHash: string;
+    status: ValidationRequestStatus;
+    highValue: boolean;
+    expiresAt: string;
+}
+export declare const validationRequestSummarySchema: z.ZodType<ValidationRequestSummary>;
+/** The result of casting a vote (`POST /civic/validations/:id/vote`). */
+export interface ValidationVoteResult {
+    recorded: true;
+    requestId: string;
+    verdict: ValidationVerdict;
+    status: ValidationRequestStatus;
+}
+export declare const validationVoteResultSchema: z.ZodType<ValidationVoteResult>;
+/**
+ * The `record` payload of a `personhood_vouch` signed envelope. The VOUCHER (B)
+ * signs this with their OWN key as a self-issued v2 record on THEIR chain
+ * (`subject === issuer === B.did`); the person being vouched for (A) is
+ * referenced by `about` (A's DID). The server resolves `about` → A's account,
+ * stakes the voucher, awards A the `personhood_vouched` points, and recomputes
+ * A's personhood.
+ *
+ * - `about` is A's DID (`did:web:oxy.so:u:<userId>`).
+ * - `context` (optional) is an opaque note from the vouching UI.
+ * - `stake` (optional) is the voucher's chosen stake; the server clamps it into
+ *   `[PERSONHOOD_VOUCH_MIN_STAKE, PERSONHOOD_VOUCH_MAX_STAKE]` and defaults it
+ *   when omitted. (Note: the wire field is `stake`, NOT `stakeAmount` — the
+ *   latter is the server's clamped, awarded value echoed in {@link VouchResult}.)
+ */
+export interface PersonhoodVouchRecord {
+    about: string;
+    context?: string;
+    stake?: number;
+}
+export declare const personhoodVouchRecordSchema: z.ZodType<PersonhoodVouchRecord>;
+/**
+ * The signal sub-scores behind a personhood score (audit / UI breakdown),
+ * mirroring the API `PersonhoodStatus` model's embedded `breakdown`.
+ */
+export interface PersonhoodBreakdown {
+    /** Saturated [0,1] vouch signal from the weighted vouch sum. */
+    vouchSignal: number;
+    /** Saturated [0,1] real-life-attestation signal. */
+    realLifeSignal: number;
+    /** 1 when the account is biometric-bound, else 0. */
+    biometricSignal: number;
+    /** Weighted blend of the three signals before the sybil penalty. */
+    evidence: number;
+    /** The [0,1] sybil penalty subtracted from the evidence. */
+    sybilPenalty: number;
+    /** True when the score came from the seed-verifier genesis short-circuit. */
+    seed: boolean;
+}
+export declare const personhoodBreakdownSchema: z.ZodType<PersonhoodBreakdown>;
+/**
+ * The public personhood status snapshot returned by
+ * `GET /civic/personhood/:userId` (and `POST /civic/personhood/:userId/recompute`).
+ * Mirrors the API `PersonhoodStatus` model's serialized response exactly — a
+ * cached, recomputable proof-of-personhood snapshot.
+ *
+ * - `score` is in `[0,1]`; `isRealPerson` is `score >= θ`.
+ * - `breakdown` is `null` ONLY on a public read of a user who has no status
+ *   document yet (the zeroed `unverified` shape); otherwise it is the full
+ *   {@link PersonhoodBreakdown}.
+ * - `updatedAt` is the ISO-8601 timestamp of the last recompute, or `null` when
+ *   no status document exists yet. (Distinct from the card's coarse
+ *   {@link PersonhoodStatus} enum, which is `'unverified' | 'pending' |
+ *   'verified'`.)
+ */
+export interface PersonhoodStatusResult {
+    userId: string;
+    score: number;
+    isRealPerson: boolean;
+    vouchCount: number;
+    realLifeCount: number;
+    biometricBound: boolean;
+    sybilPenalty: number;
+    breakdown: PersonhoodBreakdown | null;
+    updatedAt: string | null;
+}
+export declare const personhoodStatusResultSchema: z.ZodType<PersonhoodStatusResult>;
+/**
+ * The result of `POST /civic/personhood/vouch` on success: the stored vouch
+ * record id (the voucher's envelope), the subject + voucher account ids, the
+ * clamped stake the server recorded, and the points awarded to the subject.
+ */
+export interface VouchResult {
+    accepted: true;
+    recordId: string;
+    subjectUserId: string;
+    voucherUserId: string;
+    stakeAmount: number;
+    points: number;
+}
+export declare const vouchResultSchema: z.ZodType<VouchResult>;
+/** The lifecycle status of a stored verifiable credential. */
+export type CredentialStatus = 'active' | 'revoked' | 'expired';
+/**
+ * The `record` payload of a `credential` signed envelope — the W3C-VC-flavoured
+ * claim the issuer signs.
+ *
+ * - `about` is the HOLDER's DID (`did:web:oxy.so:u:<userId>`), i.e. the W3C
+ *   `credentialSubject.id`. (Named `about` to match the sibling civic records
+ *   and to avoid colliding with the envelope's own chain `subject` field.)
+ * - `types` are the VC type tags; `'VerifiableCredential'` MUST be present as the
+ *   base type, with at least one specific type (e.g. `'EmploymentCredential'`).
+ * - `claims` is the arbitrary, issuer-asserted claim set about the holder.
+ * - `expiresAt` (optional) is epoch milliseconds; absent = non-expiring. It is
+ *   part of the signed bytes, so a holder cannot extend a credential's validity.
+ */
+export interface CredentialRecord {
+    about: string;
+    types: string[];
+    claims: Record<string, unknown>;
+    expiresAt?: number;
+}
+export declare const credentialRecordSchema: z.ZodType<CredentialRecord>;
+/**
+ * The serialized verifiable credential as returned by the list + verify routes.
+ * `issuerUserId` is present only for user-issued credentials (absent for
+ * app/org-issued credentials signed by the Oxy custodial key). All timestamps
+ * are epoch milliseconds.
+ */
+export interface VerifiableCredentialResponse {
+    id: string;
+    recordId: string;
+    holderUserId: string;
+    holderDid: string;
+    issuerUserId?: string;
+    issuerDid: string;
+    types: string[];
+    claims: Record<string, unknown>;
+    status: CredentialStatus;
+    issuedAt: number;
+    expiresAt?: number;
+    revokedAt?: number;
+}
+export declare const verifiableCredentialResponseSchema: z.ZodType<VerifiableCredentialResponse>;
+/** The result of `POST /civic/credentials` on success. */
+export interface CredentialIssueResult {
+    accepted: true;
+    credential: VerifiableCredentialResponse;
+}
+export declare const credentialIssueResultSchema: z.ZodType<CredentialIssueResult>;
+/** The result of `GET /civic/credentials/:holderUserId` (list). */
+export interface CredentialListResult {
+    credentials: VerifiableCredentialResponse[];
+}
+export declare const credentialListResultSchema: z.ZodType<CredentialListResult>;
+/**
+ * The result of `GET /civic/credentials/by-record/:recordId/verify`. `valid` is
+ * `true` ONLY when the signature verifies against a CURRENT verification method
+ * of the issuer DID AND the credential is neither revoked nor expired. `reason`
+ * is a stable, machine-readable rejection code when `valid` is `false`.
+ * `credential` is `null` when no credential exists for the record id.
+ */
+export interface CredentialVerifyResult {
+    valid: boolean;
+    reason?: string;
+    credential: VerifiableCredentialResponse | null;
+}
+export declare const credentialVerifyResultSchema: z.ZodType<CredentialVerifyResult>;

package/dist/types/commonsSignIn.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Canonical contract for the "Sign in with Oxy" approval handoff.
+ *
+ * SINGLE SOURCE OF TRUTH for the closed set of reasons an approver may attach
+ * when it DENIES a pending request via
+ * `POST /auth/session/deny/:authorizeCode`.
+ *
+ * That endpoint is UNAUTHENTICATED — the public `authorizeCode` is the only
+ * credential — so a free-form string from it is never stored: it would be an
+ * unauthenticated write of arbitrary text onto a record other surfaces read.
+ * The set is therefore deliberately tiny, and closed:
+ *
+ *  - `'declined'` the approver rejected a request they recognised ("Not now").
+ *  - `'not_me'`   the approver did not start the request ("This wasn't me").
+ *                 The ONE value that records the denial as suspicious rather
+ *                 than an ordinary cancel, so a UI may only offer it where the
+ *                 user genuinely said so.
+ *
+ * Why this lives in `@oxy.so/contracts` rather than in either consumer: the same
+ * closed set is enforced in three places — the request schema of the API route,
+ * the `enum` of the persisted `AuthSession.deniedReason` field, and the client
+ * SDK's `denyCommonsSignIn` parameter. Two hand-maintained copies of a wire
+ * contract drift the moment a value is added on one side only, and the failure
+ * lands at runtime, in an auth path, as a generic validation error. One
+ * declaration makes that impossible.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/**
+ * The closed set, as a value — consumed directly where a runtime list is
+ * required (e.g. the Mongoose `enum` of `AuthSession.deniedReason`, which is
+ * the storage-level guarantee that an unauthenticated caller can never write
+ * free-form text into the field).
+ */
+export declare const COMMONS_DENY_REASONS: readonly ["declined", "not_me"];
+/**
+ * The same set as a zod enum — the edge validator. Anything outside it
+ * (including free-form text) is rejected with 400 before any handler runs.
+ */
+export declare const commonsDenyReasonSchema: z.ZodEnum<["declined", "not_me"]>;
+/** Why the approver denied a "Sign in with Oxy" request. */
+export type CommonsDenyReason = z.infer<typeof commonsDenyReasonSchema>;
+/**
+ * Android notification channel id the identity-approval push is sent on.
+ *
+ * A wire contract for the same reason the deny set is: Android 8+ DROPS a
+ * notification whose channel id the app has not created, silently and with no
+ * client-side error. The API attaches this id when it sends, and the vault
+ * creates the channel with it before registering a push token — two hand-typed
+ * copies of that string would fail as "the notification never arrived", which
+ * is the single hardest push symptom to diagnose.
+ *
+ * The channel's user-visible NAME and description are deliberately NOT here:
+ * those are localized app copy, and the vault owns them.
+ */
+export declare const IDENTITY_APPROVAL_PUSH_CHANNEL = "auth-approval";

package/dist/types/deviceBoot.d.ts

@@ -0,0 +1,74 @@
+/**
+ * First-party login result contract.
+ *
+ * SINGLE SOURCE OF TRUTH for the first-party login result (the session arm). The
+ * API validates its OUTPUT against this schema; every consumer (`@oxy.so/core`'s
+ * auth mixin) validates its INPUT against the same definition, so producer and
+ * consumers cannot drift. Sign-in is passkey (WebAuthn) or Commons handoff —
+ * password and 2FA were removed, so the only outcome is a completed session.
+ *
+ * The device transport is `deviceId` + `deviceSecret` + `POST /session/device/token`
+ * (see `deviceSession.ts`). The legacy cookie/bootstrap/refresh-family lanes were
+ * removed in the zero-cookie cutover — nothing here carries a refresh token or a
+ * boot fragment.
+ *
+ * Nested-object response shapes are declared as explicit `interface`s with the
+ * runtime schema annotated `z.ZodType<Interface>` — the same rationale as
+ * `identity.ts` / `userResponse.ts`: a `z.infer<>` of a nested object schema can
+ * degrade to `{}` under a consumer's `moduleResolution: "node"` (node10), so the
+ * load-bearing shapes are pinned by literal interfaces. Flat request/response
+ * shapes (no nested-object hazard) are inferred via `z.infer<>`.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/** One anomalous signal the server flagged on a sign-in (new device, location, …). */
+export interface SecurityAlertAnomaly {
+    type: string;
+    reason: string;
+    details?: string;
+}
+/**
+ * The "New sign-in detected" payload the API attaches to a successful
+ * `POST /auth/login` when anomaly detection fires (`session.controller.ts`).
+ * The IdP renders `message` and gates the flow on user acknowledgement before
+ * continuing to the OAuth authorize step.
+ */
+export interface SecurityAlert {
+    message: string;
+    anomalies: SecurityAlertAnomaly[];
+}
+/**
+ * A successful sign-in. Matches the API's `SessionAuthResponse` EXACTLY
+ * (`buildSessionAuthResponse`). `user` is the truncated session-user shape the
+ * sign-in endpoints emit (NOT the full `userResponseSchema`).
+ */
+export interface LoginSessionResult {
+    sessionId: string;
+    deviceId: string;
+    expiresAt: string;
+    accessToken?: string;
+    /**
+     * The device secret (zero-cookie transport). Emitted on every successful
+     * sign-in; the client persists it first-party alongside `deviceId` and later
+     * mints access tokens via `POST /session/device/token`. Optional only because
+     * a best-effort mint can fail — it is the sole restore credential.
+     */
+    deviceSecret?: string;
+    /**
+     * Present only when the server's anomaly detection flagged this sign-in.
+     * The IdP shows a "New sign-in detected" acknowledgement before proceeding.
+     * The session is already established regardless — this is an interstitial,
+     * not a gate on the credential check.
+     */
+    securityAlert?: SecurityAlert;
+    user: {
+        id: string;
+        username?: string;
+        avatar?: string;
+    };
+}
+/** The outcome of a successful sign-in — always a completed session. */
+export type LoginResult = LoginSessionResult;
+export declare const loginResultSchema: z.ZodType<LoginResult>;