@oxyhq/core 3.11.0 → 3.12.0

package/dist/types/crypto/signatureService.d.ts

@@ -10,17 +10,42 @@ import type { SignedRecordEnvelope } from '@oxyhq/contracts';
  * EXCEPT the `publicKey` and `signature`. Both the client (when signing) and
  * the server (when verifying) canonicalize exactly these fields, so they agree
  * on the bytes that the signature covers.
+ *
+ * The v2 chain fields (`seq`/`prev`/`collection`/`rkey`) are optional: a v1
+ * envelope omits them and is signed over only the base fields; a v2 envelope
+ * carries them and includes them in the signed bytes.
  */
-export type SignedRecordSigningFields = Pick<SignedRecordEnvelope, 'version' | 'type' | 'subject' | 'issuer' | 'record' | 'issuedAt'>;
+export type SignedRecordSigningFields = Pick<SignedRecordEnvelope, 'version' | 'type' | 'subject' | 'issuer' | 'record' | 'issuedAt'> & Partial<Pick<SignedRecordEnvelope, 'seq' | 'prev' | 'collection' | 'rkey'>>;
 /**
  * Compute the canonical signing input for a signed-record envelope.
  *
- * This is the single definition of "what the signature covers": the canonical
- * JSON of `{version, type, subject, issuer, record, issuedAt}`. `@oxyhq/core`
+ * This is the single definition of "what the signature covers". `@oxyhq/core`
  * (client signing) and `@oxyhq/api` (server verification) both call this, so a
  * record signed by a client and verified by the server cannot drift.
+ *
+ * - **v1**: the canonical JSON of `{version, type, subject, issuer, record,
+ *   issuedAt}` — BYTE-IDENTICAL to the original scheme, so every signature
+ *   already in production keeps verifying.
+ * - **v2**: the canonical JSON additionally includes the hash-chain fields
+ *   `{seq, prev, collection, rkey}`. Because {@link canonicalize} sorts keys,
+ *   the on-the-wire field order is irrelevant; the resulting canonical key
+ *   order is `collection, issuedAt, issuer, prev, record, rkey, seq, subject,
+ *   type, version`. `prev` is `null` at genesis (serialized as `null`, not
+ *   omitted), so it is always part of the signed bytes.
  */
 export declare function signedRecordSigningInput(fields: SignedRecordSigningFields): string;
+/**
+ * Compute the `recordId` (content address) of a signed record: the SHA-256 hex
+ * digest of its canonical {@link signedRecordSigningInput}.
+ *
+ * Deterministic and stable across runtimes (it reuses the same canonicalization
+ * + SHA-256 the signature itself is built on). The recordId is what `prev`
+ * references in the per-subject hash chain, so `@oxyhq/core` (client) and
+ * `@oxyhq/api` (server) MUST compute it identically — both call this function.
+ * It is taken over the SIGNING input (excluding `publicKey`/`signature`), so it
+ * is a pure content address of the record's meaning, independent of who signed.
+ */
+export declare function computeRecordId(fields: SignedRecordSigningFields): Promise<string>;
 export interface SignedMessage {
     message: string;
     signature: string;
@@ -135,6 +160,32 @@ export declare class SignatureService {
      * @param record - The arbitrary record payload to attest to.
      */
     static signRecord(type: SignedRecordEnvelope['type'], subject: string, record: Record<string, unknown>): Promise<SignedRecordEnvelope>;
+    /**
+     * Build a signed-record envelope (v2) carrying the per-subject hash-chain
+     * fields.
+     *
+     * Identical to {@link signRecord} (self-issued: `issuer === subject`; same
+     * `ES256K-DER-SHA256` scheme over {@link signedRecordSigningInput}) but
+     * `version` is `2` and the signed bytes additionally cover the chain fields:
+     *
+     * @param type - The record category.
+     * @param subject - The subject DID the record is about (also the issuer).
+     * @param record - The arbitrary record payload to attest to.
+     * @param chain - The hash-chain coordinates:
+     *   - `seq` — strictly-increasing sequence number for this subject's chain.
+     *   - `prev` — the `recordId` of the previous record, or `null` at genesis.
+     *   - `collection` + `rkey` — the AtProto-style record key.
+     *
+     * The caller is responsible for fetching the current chain head (so `seq` /
+     * `prev` are correct) before signing. Requires a stored identity; throws if
+     * none exists.
+     */
+    static signRecordV2(type: SignedRecordEnvelope['type'], subject: string, record: Record<string, unknown>, chain: {
+        seq: number;
+        prev: string | null;
+        collection: string;
+        rkey: string;
+    }): Promise<SignedRecordEnvelope>;
     /**
      * Verify a signed-record envelope: recompute the canonical signing input from
      * the envelope's own fields and check the signature against the envelope's

package/dist/types/index.d.ts

@@ -39,11 +39,15 @@ export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
 export { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull, } from './utils/userIdentity';
 export { getCanonicalUserHandle, getNormalizedUserHandle, } from './utils/userHandle';
 export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHandle';
+export { normalizeProfileLinks } from './utils/profileLinks';
+export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type { Application, PublicApplication, ApplicationMember, ApplicationCredential, ApplicationRole, ApplicationType, ApplicationStatus, ApplicationMemberStatus, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, InviteApplicationMemberInput, UpdateApplicationMemberInput, TransferApplicationOwnershipInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, ApplicationSuccessResult, } from './mixins/OxyServices.applications';
 export type { Workspace, WorkspaceMember, WorkspaceRole, WorkspaceType, WorkspaceStatus, WorkspaceMemberStatus, CreateWorkspaceInput, UpdateWorkspaceInput, InviteWorkspaceMemberInput, UpdateWorkspaceMemberInput, TransferWorkspaceOwnershipInput, WorkspaceSuccessResult, } from './mixins/OxyServices.workspaces';
 export type { ReputationCategory, TrustTier, ReputationTransactionStatus, ReputationTargetEntityType, ReputationDisputeStatus, ReputationInfluenceContext, ReputationTransaction, ReputationBalanceBreakdown, ReputationInfluence, ReputationReliability, ReputationBalance, ReputationDispute, ReputationRule, ReputationLeaderboardEntry, ReputationInfluenceResult, ReverseReputationTransactionResult, AwardReputationInput, CreateReputationDisputeInput, ResolveReputationDisputeInput, UpsertReputationRuleInput, ReverseReputationTransactionInput, } from './mixins/OxyServices.reputation';
 export { buildUserDid } from './mixins/OxyServices.identity';
 export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, } from './mixins/OxyServices.identity';
+export { parseIdPayload, parseAttestPayload, verifyPublicCardAttestation, } from './mixins/OxyServices.civic';
+export type { CivicCardResult, IdCardRef, AttestQrPayload, ParsedAttestPayload, SubmitRealLifeAttestationInput, DenyValidationResult, VouchForPersonInput, WithdrawVouchResult, IssueCredentialInput, RevokeCredentialResult, } from './mixins/OxyServices.civic';
 export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers';
 export type { HandleApiErrorOptions } from './utils/authHelpers';
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual, } from './utils/sessionUtils';
@@ -51,7 +55,7 @@ export type { ClientSession, StorageKeys, MinimalUserData, SessionLoginResponse,
 export type { RefreshAllResponse, RefreshAllAccount, RefreshAllAccountUser, RefreshCookieResponse, } from './models/interfaces';
 export { KeyManager, IdentityAlreadyExistsError, IdentityPersistError, } from './crypto/keyManager';
 export type { KeyPair } from './crypto/keyManager';
-export { SignatureService, signedRecordSigningInput } from './crypto/signatureService';
+export { SignatureService, signedRecordSigningInput, computeRecordId } from './crypto/signatureService';
 export type { SignedMessage, AuthChallenge, SignedRecordSigningFields } from './crypto/signatureService';
 export { canonicalize } from './crypto/canonicalJson';
 export { RecoveryPhraseService } from './crypto/recoveryPhrase';

package/dist/types/mixins/OxyServices.civic.d.ts

@@ -0,0 +1,512 @@
+/**
+ * Civic Methods Mixin (Commons "Oxy ID" — Fase 1; anti-gaming — Fase 2)
+ *
+ * Provides typed access to the public, verifiable citizen-identity ("Oxy ID")
+ * card a Commons user shows and others scan, plus the Fase 2 anti-gaming surfaces
+ * (real-life counterparty attestation + the validator/jury flow):
+ *
+ *  - {@link OxyServicesCivicMixin.getPublicCard} fetches a user's signed card
+ *    (`GET /civic/:userId/card`) and verifies the Oxy custodial attestation
+ *    CLIENT-SIDE, so a scanner can trust the card OFFLINE (e.g. a cached card
+ *    replayed without network) instead of re-trusting the transport.
+ *  - {@link OxyServicesCivicMixin.getMyIdPayload} builds the QR payload the user
+ *    displays. The QR encodes ONLY the DID (`oxycommons://card?did=…&v=1`) — never
+ *    trust data — so the card cannot be spoofed by crafting a QR; the scanner
+ *    resolves the signed card server-side and re-verifies it.
+ *  - {@link OxyServicesCivicMixin.buildAttestQrPayload} builds the high-value
+ *    real-life-attestation QR the person BEING attested (A) shows; the SCANNER
+ *    (B) parses it with {@link parseAttestPayload} and signs a self-issued
+ *    counterparty attestation via
+ *    {@link OxyServicesCivicMixin.submitRealLifeAttestation}.
+ *  - {@link OxyServicesCivicMixin.getValidatorInbox} /
+ *    {@link OxyServicesCivicMixin.submitValidationVote} /
+ *    {@link OxyServicesCivicMixin.denyValidation} drive a randomly-selected
+ *    juror's medium-weight peer-validation duties.
+ *
+ * The wire shapes (`PublicCard`, `SignedPublicCard`, `ExportAttestation`,
+ * `RealLifeAttestationResult`, `ValidationRequestSummary`, `ValidationVoteResult`,
+ * `SignedRecordEnvelope`) come from `@oxyhq/contracts` — the single source of
+ * truth the API validates its output against — so producer and consumer cannot
+ * drift. The public Oxy ID card's attestation is an `ES256K-DER-SHA256` signature
+ * over `canonicalize(card)` (the exact bytes the server signed, with ONLY the
+ * present keys), so a consumer re-canonicalizes the `card` it received and checks
+ * the signature against `attestation.publicKey`.
+ *
+ * Card verification NEVER throws on a bad/absent signature — it returns
+ * `verified: false` so the UI can render a forged/unsigned card as visibly
+ * untrusted rather than silently trusting it. A transport/network failure (the
+ * fetch itself) still rejects, as everywhere else in the SDK.
+ *
+ * The Fase 2 writes (`submitRealLifeAttestation`, `submitValidationVote`) sign a
+ * v2 self-issued signed-record envelope with the on-device identity key (so they
+ * are NATIVE-ONLY — they throw on web, where `KeyManager` has no key) on the
+ * caller's own per-subject hash chain: each fetches the caller's chain head
+ * (`GET /identity/records/:userId/chain/head`) to set `seq`/`prev` before signing
+ * with {@link SignatureService.signRecordV2}.
+ *
+ * Reading a public card and building/parsing the QR payloads are
+ * platform-agnostic; deriving the current user's DID requires an authenticated
+ * session.
+ */
+import type { CredentialIssueResult, CredentialListResult, CredentialStatus, CredentialVerifyResult, ExportAttestation, PersonhoodStatusResult, PublicCard, RealLifeAttestationResult, SignedPublicCard, SignedRecordEnvelope, SignedRecordType, ValidationRequestSummary, ValidationVerdict, ValidationVoteResult, VerifiableCredentialResponse, VouchResult } from '@oxyhq/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+/**
+ * A {@link SignedPublicCard} augmented with the client's verification verdict.
+ *
+ * - `card` / `attestation` are echoed straight from the API response.
+ * - `verified` is `true` ONLY when `attestation` is present and its signature
+ *   over `canonicalize(card)` checks out against `attestation.publicKey`. It is
+ *   `false` for an unsigned card (dev, `attestation === null`), a tampered card,
+ *   or a signature made with a different key.
+ *
+ * `verified` confirms the attestation's signature is internally consistent with
+ * its embedded `publicKey` (and that the card bytes were not mutated). It does
+ * NOT, on its own, establish that `publicKey` is Oxy's custodial key — that trust
+ * anchor is the Oxy API the card was fetched from (over TLS) and, for the
+ * pinning-conscious, `attestation.issuer` (the Oxy DID). The UI shows a trust
+ * indicator from `verified`; a `false` verdict MUST be surfaced as untrusted.
+ */
+export interface CivicCardResult extends SignedPublicCard {
+    verified: boolean;
+}
+/** The DID extracted from a scanned `oxycommons://card?did=…` Oxy ID payload. */
+export interface IdCardRef {
+    /** The subject's Oxy DID (`did:web:oxy.so:u:<userId>`). */
+    did: string;
+}
+/**
+ * Parse a scanned / deep-linked Oxy ID payload (`oxycommons://card?did=…`) into
+ * the referenced DID. Pure + dependency-free (Hermes-safe, no `URL` global) so
+ * Commons (and any scanner) can reuse it without an OxyServices instance.
+ *
+ * @param raw - The raw scanned string or deep-link URL.
+ * @returns `{ did }` when a usable DID is present; `null` for anything else (a
+ *   non-card scheme, a missing/empty `did`, or non-string input).
+ */
+export declare function parseIdPayload(raw: string): IdCardRef | null;
+/**
+ * The fields decoded from a scanned real-life-attestation QR
+ * (`oxycommons://attest?subject=…&ctx=…&nonce=…&exp=…`). The SCANNER feeds these
+ * to {@link OxyServicesCivicMixin.submitRealLifeAttestation}.
+ */
+export interface ParsedAttestPayload {
+    /** The DID of the person being attested (A) — becomes the record's `about`. */
+    subjectDid: string;
+    /** Opaque interaction id (`ctx`); `''` when the QR omitted it. */
+    context: string;
+    /** Single-use replay-guard nonce. */
+    nonce: string;
+    /** Nonce expiry (epoch ms); the server re-checks freshness authoritatively. */
+    exp: number;
+}
+/**
+ * The QR a person shows to be attested in real life, plus the fresh nonce/exp it
+ * embeds so the displaying app can track which scan completed it.
+ */
+export interface AttestQrPayload {
+    /** The `oxycommons://attest?subject=…&ctx=…&nonce=…&exp=…` string to encode as a QR. */
+    payload: string;
+    /** The single-use nonce embedded in the payload. */
+    nonce: string;
+    /** The nonce expiry embedded in the payload (epoch ms). */
+    exp: number;
+}
+/**
+ * Parse a scanned / deep-linked real-life-attestation payload
+ * (`oxycommons://attest?subject=…&ctx=…&nonce=…&exp=…`). Pure + dependency-free
+ * (Hermes-safe, no `URL` global), mirroring {@link parseIdPayload}, so Commons
+ * (and any scanner) can reuse it without an OxyServices instance.
+ *
+ * @param raw - The raw scanned string or deep-link URL.
+ * @returns `{ subjectDid, context, nonce, exp }` when the required fields are
+ *   present and `exp` is a positive finite number; `null` otherwise (a non-attest
+ *   scheme, a missing `subject`/`nonce`/`exp`, an unparseable `exp`, or non-string
+ *   input). `context` defaults to `''` when the QR omits `ctx`.
+ */
+export declare function parseAttestPayload(raw: string): ParsedAttestPayload | null;
+/**
+ * Verify the Oxy custodial attestation on a public card.
+ *
+ * Re-canonicalizes the received `card` (so the order of the JSON keys on the
+ * wire is irrelevant; `canonicalize` also omits any `undefined`-valued optional
+ * key, matching the server which omits absent keys entirely) and checks the
+ * `ES256K-DER-SHA256` signature against `attestation.publicKey`.
+ *
+ * NEVER throws: `SignatureService.verify` already swallows malformed-input
+ * errors and returns `false`, and an absent attestation short-circuits to
+ * `false`. A pure, reusable helper (Commons can call it on a cached card).
+ *
+ * @param card - The card to verify (exactly as received).
+ * @param attestation - The card's attestation, or `null` (unsigned ⇒ `false`).
+ */
+export declare function verifyPublicCardAttestation(card: PublicCard, attestation: ExportAttestation | null): Promise<boolean>;
+/**
+ * Input for {@link OxyServicesCivicMixin.submitRealLifeAttestation} — the fields
+ * the SCANNER (B) carries over from a parsed {@link ParsedAttestPayload}, plus
+ * the optional co-location / biometric support signals B contributes.
+ */
+export interface SubmitRealLifeAttestationInput {
+    /** The DID of the person being attested (A); becomes the record's `about`. */
+    subjectDid: string;
+    /** Opaque interaction id from the QR. */
+    context: string;
+    /** Single-use nonce from the QR (also the record's `rkey`). */
+    nonce: string;
+    /** Nonce expiry from the QR (epoch ms). */
+    exp: number;
+    /** Coarse co-location proof (optional). */
+    geohash?: string;
+    /** Whether B's device biometric gate fired before signing (optional). */
+    biometricOk?: boolean;
+}
+/** Result of {@link OxyServicesCivicMixin.denyValidation}. */
+export interface DenyValidationResult {
+    denied: boolean;
+}
+/**
+ * Input for {@link OxyServicesCivicMixin.vouchForPerson} — the SUBJECT (A) the
+ * current user (B) is vouching for, plus B's optional stake and biometric
+ * support signal.
+ */
+export interface VouchForPersonInput {
+    /** A's DID (`did:web:oxy.so:u:<userId>`); becomes the vouch record's `about`. */
+    subjectDid: string;
+    /**
+     * B's chosen stake (the `stake` wire field). Omitted ⇒ the server applies its
+     * default; the server clamps any value into its `[min, max]` and echoes the
+     * recorded amount back as `VouchResult.stakeAmount`.
+     */
+    stakeAmount?: number;
+    /** Whether B's device biometric gate fired before signing (optional signal). */
+    biometricOk?: boolean;
+}
+/** Result of {@link OxyServicesCivicMixin.withdrawVouch}. */
+export interface WithdrawVouchResult {
+    withdrawn: boolean;
+}
+/**
+ * Input for {@link OxyServicesCivicMixin.issueCredential} — the HOLDER the
+ * caller (issuer) attests a claim about, the VC type tags, the issuer's claim
+ * set, and an optional ISO-8601 expiry.
+ */
+export interface IssueCredentialInput {
+    /** The holder's Oxy DID (`did:web:oxy.so:u:<userId>`); becomes the record's `about`. */
+    holderDid: string;
+    /**
+     * The VC type tags. `'VerifiableCredential'` is the required base type and is
+     * prepended automatically when the caller omits it; provide at least one
+     * specific type alongside (e.g. `'EmploymentCredential'`).
+     */
+    types: string[];
+    /** The arbitrary, issuer-asserted claim set about the holder (signed verbatim). */
+    claims: Record<string, unknown>;
+    /**
+     * Optional expiry as an ISO-8601 date string; absent = non-expiring. Converted
+     * to epoch milliseconds in the signed record (the wire/storage unit), so a
+     * holder cannot extend validity after the fact. Must be a parseable date and,
+     * per the server, in the future.
+     */
+    expiresAt?: string;
+}
+/** Result of {@link OxyServicesCivicMixin.revokeCredential} (`POST …/:id/revoke`). */
+export interface RevokeCredentialResult {
+    revoked: boolean;
+    credential: VerifiableCredentialResponse;
+}
+export declare function OxyServicesCivicMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Fetch a user's signed public Oxy ID card and verify the Oxy attestation
+         * client-side. Public (no auth required); short-TTL cached.
+         *
+         * Resolves to `{ card, attestation, verified }`. A bad/absent signature does
+         * NOT reject — it yields `verified: false` so the UI can warn. Only a
+         * transport failure (the fetch itself) rejects.
+         *
+         * @param userId - The subject account's Mongo `_id`. URL-encoded into the path.
+         */
+        getPublicCard(userId: string): Promise<CivicCardResult>;
+        /**
+         * Build the Oxy ID QR payload for the current user:
+         * `oxycommons://card?did=<did>&v=1`, where `<did>` is the user's Oxy DID
+         * (`did:web:oxy.so:u:<userId>`). The QR encodes ONLY the DID (anti-spoof — no
+         * trust data); a scanner resolves the signed card via {@link getPublicCard}.
+         * Round-trips through {@link parseIdPayload}.
+         *
+         * Throws if no user is authenticated (no DID to derive).
+         */
+        getMyIdPayload(): string;
+        /**
+         * Build the real-life-attestation QR the current user (A) shows to be
+         * attested by a counterparty (B):
+         * `oxycommons://attest?subject=<A.did>&ctx=<context>&nonce=<fresh>&exp=<now+10m>`.
+         *
+         * A fresh crypto-random nonce is minted per call (single-use replay guard);
+         * `exp` is `now + 10min` (matching the server ceiling — scan promptly). The
+         * QR carries NO trust data; B re-signs and the server is authoritative. The
+         * returned `nonce`/`exp` let the displaying screen track which scan completed.
+         *
+         * Async because a crypto-secure nonce requires the platform RNG (async on
+         * native via expo-crypto). Throws if no user is authenticated.
+         *
+         * @param input.context - An opaque interaction id describing the encounter.
+         */
+        buildAttestQrPayload(input: {
+            context: string;
+        }): Promise<AttestQrPayload>;
+        /**
+         * Submit a real-life counterparty attestation as the SCANNER (B): sign a
+         * self-issued `real_life_attestation` v2 record on B's own chain
+         * (`subject === issuer === B.did`), referencing A via `record.about`, then
+         * `POST /civic/attestations`. The server enforces nonce single-use,
+         * freshness, graph-exclusion (B is not A's puppet), and the per-pair
+         * cooldown, then awards A the HIGH-weight points.
+         *
+         * NATIVE-ONLY (signs with the on-device key; throws on web / when no
+         * identity or no authenticated user). The record is keyed
+         * `collection: 'app.oxy.attestation'`, `rkey: <nonce>`.
+         *
+         * @param input - The parsed QR fields ({@link ParsedAttestPayload}) plus B's
+         *   optional `geohash` / `biometricOk` support signals.
+         */
+        submitRealLifeAttestation(input: SubmitRealLifeAttestationInput): Promise<RealLifeAttestationResult>;
+        /**
+         * List the current user's pending jury duties (`GET /civic/validations/inbox`).
+         * Auth required; never cached (the inbox is a live queue). Returns `[]` when
+         * the caller is on no juries.
+         */
+        getValidatorInbox(): Promise<ValidationRequestSummary[]>;
+        /**
+         * Cast a SIGNED verdict on a validation request as a selected juror: sign a
+         * self-issued `validation_verdict` v2 record on the juror's own chain bound
+         * to `requestId` + `payloadHash` (so a verdict cannot be replayed onto a
+         * different request or an altered payload), then
+         * `POST /civic/validations/:id/vote`.
+         *
+         * NATIVE-ONLY (signs with the on-device key; throws on web / when no
+         * identity or no authenticated user). The record is keyed
+         * `collection: 'app.oxy.validation'`, `rkey: <requestId>`.
+         *
+         * @param requestId - The validation request being voted on.
+         * @param payloadHash - The request's canonical payload hash (from the inbox);
+         *   the server rejects a vote whose hash does not match the stored request.
+         * @param verdict - `'valid'` | `'invalid'` | `'abstain'`.
+         */
+        submitValidationVote(requestId: string, payloadHash: string, verdict: ValidationVerdict): Promise<ValidationVoteResult>;
+        /**
+         * Recuse from a validation request (`POST /civic/validations/:id/deny`): the
+         * juror is removed from the jury and the request is re-tallied. Auth
+         * required; no signed record (recusal is not an attestation).
+         *
+         * @param requestId - The validation request to recuse from.
+         */
+        denyValidation(requestId: string): Promise<DenyValidationResult>;
+        /**
+         * Vouch that another user is a real person as the VOUCHER (B): sign a
+         * self-issued `personhood_vouch` v2 record on B's own chain
+         * (`subject === issuer === B.did`), referencing the subject (A) via
+         * `record.about`, then `POST /civic/personhood/vouch`. The server verifies
+         * it, enforces the voucher-eligibility (personhood ≥ τ) + graph-exclusion
+         * gates, stakes B, awards A `personhood_vouched`, and recomputes A's
+         * personhood. The voucher id is resolved server-side from the session — never
+         * from the body.
+         *
+         * The signed record matches the API schema: `{ about, stake?, … }` — note the
+         * wire field is `stake` (the caller's `stakeAmount` request), distinct from
+         * the server-clamped `VouchResult.stakeAmount` it returns. The optional
+         * `biometricOk` is carried as a signed support signal.
+         *
+         * NATIVE-ONLY (signs with the on-device key; throws on web / when no identity
+         * or no authenticated user). The record is keyed
+         * `collection: 'app.oxy.vouch'`, `rkey: <subjectDid>` (one vouch per subject
+         * on the voucher's chain — last-writer-wins). After a successful vouch the
+         * personhood + `/users/me` GET caches are swept.
+         *
+         * @param input - The subject DID plus B's optional stake / biometric signal.
+         */
+        vouchForPerson(input: VouchForPersonInput): Promise<VouchResult>;
+        /**
+         * Withdraw the current user's active vouch for a subject
+         * (`DELETE /civic/personhood/vouch/:subjectUserId`). The vouch flips to
+         * `withdrawn` server-side and the subject is recomputed (which may demote
+         * them below θ). Auth required; no signed record (withdrawal is not an
+         * attestation). After a successful withdraw the personhood + `/users/me` GET
+         * caches are swept.
+         *
+         * @param subjectUserId - The subject account's Mongo `_id` (NOT a DID) — the
+         *   id the server keys the vouch on. URL-encoded into the path.
+         */
+        withdrawVouch(subjectUserId: string): Promise<WithdrawVouchResult>;
+        /**
+         * Fetch a user's public personhood status snapshot
+         * (`GET /civic/personhood/:userId`). Read-only: the server returns the cached
+         * snapshot, or a zeroed `unverified` shape (`breakdown`/`updatedAt` null) when
+         * none exists yet. Public (no auth required); short-TTL cached.
+         *
+         * @param userId - The subject account's Mongo `_id`. URL-encoded into the path.
+         */
+        getPersonhood(userId: string): Promise<PersonhoodStatusResult>;
+        /**
+         * Fetch the CURRENT user's personhood status ({@link getPersonhood} for the
+         * authenticated user's id). Throws if no user is authenticated.
+         */
+        getMyPersonhood(): Promise<PersonhoodStatusResult>;
+        /**
+         * Issue a verifiable credential as the ISSUER: sign a self-issued
+         * `credential` v2 record on the caller's own chain
+         * (`subject === issuer === issuer.did`) whose `record.about` is the HOLDER's
+         * DID (the W3C `credentialSubject`), then `POST /civic/credentials`. The
+         * server verifies the signature + the issuer's CURRENT verification method +
+         * chain continuity, stores the signed record, and projects a queryable
+         * credential row. All claim data comes from the SIGNED envelope — the issuer
+         * id is resolved server-side from the session, never from the body.
+         *
+         * `'VerifiableCredential'` is ensured present as the base type (prepended
+         * when the caller omits it; the server rejects a record missing it). An
+         * `expiresAt` ISO string is converted to the epoch-ms the signed record
+         * carries (the server rejects a past expiry).
+         *
+         * NATIVE-ONLY (signs with the on-device key; throws on web / when no identity
+         * or no authenticated user). The record is keyed
+         * `collection: 'app.oxy.credential'`, `rkey: <fresh unique nonce>` (each
+         * credential is a distinct chain entry, so the rkey must be unique per
+         * credential). After a successful issue the credential GET caches are swept.
+         *
+         * @param input - The holder DID, VC types, claims, and optional ISO expiry.
+         */
+        issueCredential(input: IssueCredentialInput): Promise<CredentialIssueResult>;
+        /**
+         * List a holder's verifiable credentials
+         * (`GET /civic/credentials/:holderUserId`), newest first, optionally filtered
+         * by stored `status`. Public (credentials are issuer-signed attestations a
+         * holder collects to SHOW); short-TTL cached and swept after the caller's own
+         * issue / revoke. An unknown holder yields an empty list.
+         *
+         * @param holderUserId - The holder account's Mongo `_id` (NOT a DID). URL-encoded.
+         * @param opts.status - Optional `'active' | 'revoked' | 'expired'` filter.
+         */
+        listCredentials(holderUserId: string, opts?: {
+            status?: CredentialStatus;
+        }): Promise<CredentialListResult>;
+        /**
+         * List the CURRENT user's verifiable credentials ({@link listCredentials} for
+         * the authenticated user's id). Throws if no user is authenticated.
+         *
+         * @param opts.status - Optional status filter.
+         */
+        listMyCredentials(opts?: {
+            status?: CredentialStatus;
+        }): Promise<CredentialListResult>;
+        /**
+         * Verify a credential by its signed-record id
+         * (`GET /civic/credentials/by-record/:recordId/verify`). The server recomputes
+         * the canonical signing input from the STORED envelope and verifies the
+         * signature against a CURRENT verification method of the ISSUER DID (so a
+         * key the issuer has since rotated away no longer verifies), then checks the
+         * credential is neither revoked nor expired. Public; short-TTL cached
+         * (matching the server's `max-age=60`) and swept after the caller's own issue
+         * / revoke.
+         *
+         * A revoked / expired / unverifiable credential yields `valid: false` (NOT a
+         * throw) so the UI can render it as untrusted; `credential` is `null` only
+         * when no credential exists for the record id. Only a transport failure (the
+         * fetch itself) rejects.
+         *
+         * @param recordId - The credential's signed-record id. URL-encoded into the path.
+         */
+        verifyCredential(recordId: string): Promise<CredentialVerifyResult>;
+        /**
+         * Revoke a credential the current user originally issued
+         * (`POST /civic/credentials/:id/revoke`). Only the original USER issuer may
+         * revoke; the server flips the credential to `revoked`. After a successful
+         * revoke the credential GET caches are swept.
+         *
+         * @param id - The credential's id (the projection row `_id`, NOT the signed
+         *   record id). URL-encoded into the path.
+         */
+        revokeCredential(id: string): Promise<RevokeCredentialResult>;
+        /**
+         * Sweep the credential GET caches an issue / revoke invalidates: every
+         * credential read (the holder list + the by-record verify, which share the
+         * `GET:/civic/credentials/` prefix) so a re-read reflects the new credential
+         * set / status. Public rather than `private` for the same TS4094 reason as
+         * {@link _signMyCivicRecordV2}.
+         */
+        _sweepCredentialCaches(): void;
+        /**
+         * Sweep the GET caches a vouch / withdraw can invalidate: every personhood
+         * status read (the subject's snapshot changed) and `/users/me` (a subject
+         * crossing the threshold flips their mirrored `User.verified`). Public rather
+         * than `private` for the same TS4094 reason as {@link _signMyCivicRecordV2}.
+         */
+        _sweepPersonhoodCaches(): void;
+        /**
+         * Sign a self-issued v2 signed-record envelope on the CURRENT user's own
+         * per-subject hash chain. Fetches the caller's chain head fresh (uncached, so
+         * `seq`/`prev` are never stale → no `bad_seq`/`chain_fork`) and signs with
+         * {@link SignatureService.signRecordV2}.
+         *
+         * NATIVE-ONLY (the private key lives in native secure storage). Internal
+         * helper (leading underscore); public rather than `private` because mixins
+         * compose into an exported anonymous class where TypeScript cannot represent a
+         * private member in the emitted declaration file (TS4094).
+         *
+         * @param type - The signed-record category.
+         * @param record - The record payload (canonicalized into the signed bytes).
+         * @param collection - The AtProto-style collection namespace.
+         * @param rkey - The AtProto-style record key within the collection.
+         */
+        _signMyCivicRecordV2(type: SignedRecordType, record: Record<string, unknown>, collection: string, rkey: string): Promise<SignedRecordEnvelope>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getSessionBaseUrl(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        setActingAs(userId: string | null): void;
+        getActingAs(): string | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

package/dist/types/mixins/index.d.ts

@@ -29,6 +29,7 @@ import { OxyServicesTopicsMixin } from './OxyServices.topics';
 import { OxyServicesManagedAccountsMixin } from './OxyServices.managedAccounts';
 import { OxyServicesContactsMixin } from './OxyServices.contacts';
 import { OxyServicesAppDataMixin } from './OxyServices.appData';
+import { OxyServicesCivicMixin } from './OxyServices.civic';
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
  * `composeOxyServices()` produces a class whose instances expose all of
@@ -38,7 +39,7 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSilentAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesApplicationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesWorkspacesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSilentAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesApplicationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesWorkspacesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline