@oxyhq/contracts 0.3.0 → 0.5.0

package/dist/cjs/civic.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.credentialVerifyResultSchema = exports.credentialListResultSchema = exports.credentialIssueResultSchema = exports.verifiableCredentialResponseSchema = exports.credentialRecordSchema = exports.vouchResultSchema = exports.personhoodStatusResultSchema = exports.personhoodBreakdownSchema = exports.personhoodVouchRecordSchema = exports.validationVoteResultSchema = exports.validationRequestSummarySchema = exports.validationOpenResultSchema = exports.validationOpenRequestSchema = exports.validationVerdictRecordSchema = exports.realLifeAttestationResultSchema = exports.realLifeAttestationRecordSchema = exports.signedPublicCardSchema = exports.publicCardSchema = void 0;
+const zod_1 = require("zod");
+const identity_1 = require("./identity");
+exports.publicCardSchema = zod_1.z.object({
+    did: zod_1.z.string(),
+    userId: zod_1.z.string(),
+    name: zod_1.z.string(),
+    username: zod_1.z.string().optional(),
+    avatarUrl: zod_1.z.string().optional(),
+    trustTier: zod_1.z.enum(['restricted', 'new', 'trusted', 'high_trust', 'verified']),
+    personhoodStatus: zod_1.z.enum(['unverified', 'pending', 'verified']),
+    verifiedDomains: zod_1.z.array(zod_1.z.string()),
+    credentialBadges: zod_1.z.array(zod_1.z.string()),
+    issuedAt: zod_1.z.number(),
+});
+exports.signedPublicCardSchema = zod_1.z.object({
+    card: exports.publicCardSchema,
+    attestation: identity_1.exportAttestationSchema.nullable(),
+});
+exports.realLifeAttestationRecordSchema = zod_1.z.object({
+    about: zod_1.z.string(),
+    context: zod_1.z.string(),
+    nonce: zod_1.z.string(),
+    exp: zod_1.z.number(),
+    geohash: zod_1.z.string().optional(),
+    biometricOk: zod_1.z.boolean().optional(),
+});
+exports.realLifeAttestationResultSchema = zod_1.z.object({
+    accepted: zod_1.z.literal(true),
+    recordId: zod_1.z.string(),
+    subjectUserId: zod_1.z.string(),
+    attestorUserId: zod_1.z.string(),
+    points: zod_1.z.number(),
+});
+exports.validationVerdictRecordSchema = zod_1.z.object({
+    requestId: zod_1.z.string(),
+    payloadHash: zod_1.z.string(),
+    verdict: zod_1.z.enum(['valid', 'invalid', 'abstain']),
+});
+/** Request body for opening a validation request (`POST /civic/validations`). */
+exports.validationOpenRequestSchema = zod_1.z.object({
+    subjectUserId: zod_1.z.string(),
+    actionType: zod_1.z.string().min(1),
+    sourceActionId: zod_1.z.string().min(1),
+    payload: zod_1.z.record(zod_1.z.unknown()),
+    highValue: zod_1.z.boolean().optional(),
+});
+exports.validationOpenResultSchema = zod_1.z.object({
+    requestId: zod_1.z.string(),
+    selectedValidatorCount: zod_1.z.number(),
+    expiresAt: zod_1.z.string(),
+});
+exports.validationRequestSummarySchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    subjectUserId: zod_1.z.string(),
+    actionType: zod_1.z.string(),
+    payload: zod_1.z.record(zod_1.z.unknown()),
+    payloadHash: zod_1.z.string(),
+    status: zod_1.z.enum(['pending', 'quorum_met', 'validated', 'rejected', 'expired']),
+    highValue: zod_1.z.boolean(),
+    expiresAt: zod_1.z.string(),
+});
+exports.validationVoteResultSchema = zod_1.z.object({
+    recorded: zod_1.z.literal(true),
+    requestId: zod_1.z.string(),
+    verdict: zod_1.z.enum(['valid', 'invalid', 'abstain']),
+    status: zod_1.z.enum(['pending', 'quorum_met', 'validated', 'rejected', 'expired']),
+});
+exports.personhoodVouchRecordSchema = zod_1.z.object({
+    about: zod_1.z.string(),
+    context: zod_1.z.string().optional(),
+    stake: zod_1.z.number().optional(),
+});
+exports.personhoodBreakdownSchema = zod_1.z.object({
+    vouchSignal: zod_1.z.number(),
+    realLifeSignal: zod_1.z.number(),
+    biometricSignal: zod_1.z.number(),
+    evidence: zod_1.z.number(),
+    sybilPenalty: zod_1.z.number(),
+    seed: zod_1.z.boolean(),
+});
+exports.personhoodStatusResultSchema = zod_1.z.object({
+    userId: zod_1.z.string(),
+    score: zod_1.z.number(),
+    isRealPerson: zod_1.z.boolean(),
+    vouchCount: zod_1.z.number(),
+    realLifeCount: zod_1.z.number(),
+    biometricBound: zod_1.z.boolean(),
+    sybilPenalty: zod_1.z.number(),
+    breakdown: exports.personhoodBreakdownSchema.nullable(),
+    updatedAt: zod_1.z.string().nullable(),
+});
+exports.vouchResultSchema = zod_1.z.object({
+    accepted: zod_1.z.literal(true),
+    recordId: zod_1.z.string(),
+    subjectUserId: zod_1.z.string(),
+    voucherUserId: zod_1.z.string(),
+    stakeAmount: zod_1.z.number(),
+    points: zod_1.z.number(),
+});
+exports.credentialRecordSchema = zod_1.z.object({
+    about: zod_1.z.string(),
+    types: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    claims: zod_1.z.record(zod_1.z.unknown()),
+    expiresAt: zod_1.z.number().optional(),
+});
+exports.verifiableCredentialResponseSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    recordId: zod_1.z.string(),
+    holderUserId: zod_1.z.string(),
+    holderDid: zod_1.z.string(),
+    issuerUserId: zod_1.z.string().optional(),
+    issuerDid: zod_1.z.string(),
+    types: zod_1.z.array(zod_1.z.string()),
+    claims: zod_1.z.record(zod_1.z.unknown()),
+    status: zod_1.z.enum(['active', 'revoked', 'expired']),
+    issuedAt: zod_1.z.number(),
+    expiresAt: zod_1.z.number().optional(),
+    revokedAt: zod_1.z.number().optional(),
+});
+exports.credentialIssueResultSchema = zod_1.z.object({
+    accepted: zod_1.z.literal(true),
+    credential: exports.verifiableCredentialResponseSchema,
+});
+exports.credentialListResultSchema = zod_1.z.object({
+    credentials: zod_1.z.array(exports.verifiableCredentialResponseSchema),
+});
+exports.credentialVerifyResultSchema = zod_1.z.object({
+    valid: zod_1.z.boolean(),
+    reason: zod_1.z.string().optional(),
+    credential: exports.verifiableCredentialResponseSchema.nullable(),
+});

package/dist/cjs/identity.js

@@ -62,16 +62,97 @@ exports.didDocumentSchema = zod_1.z.object({
     alsoKnownAs: zod_1.z.array(zod_1.z.string()),
     service: zod_1.z.array(exports.didServiceSchema),
 });
-exports.signedRecordEnvelopeSchema = zod_1.z.object({
-    version: zod_1.z.literal(1),
-    type: zod_1.z.enum(['identity', 'profile']),
+exports.signedRecordEnvelopeSchema = zod_1.z
+    .object({
+    version: zod_1.z.union([zod_1.z.literal(1), zod_1.z.literal(2)]),
+    type: zod_1.z.enum([
+        'identity',
+        'profile',
+        'reputation_attestation',
+        'real_life_attestation',
+        'validation_verdict',
+        'personhood_vouch',
+        'credential',
+        'node',
+    ]),
     subject: zod_1.z.string(),
     issuer: zod_1.z.string(),
     record: zod_1.z.record(zod_1.z.unknown()),
     issuedAt: zod_1.z.number(),
+    seq: zod_1.z.number().int().nonnegative().optional(),
+    prev: zod_1.z.string().nullable().optional(),
+    collection: zod_1.z.string().min(1).optional(),
+    rkey: zod_1.z.string().min(1).optional(),
     publicKey: zod_1.z.string(),
     alg: zod_1.z.literal('ES256K-DER-SHA256'),
     signature: zod_1.z.string(),
+})
+    .superRefine((env, ctx) => {
+    if (env.version === 2) {
+        // v2 REQUIRES the hash-chain fields. `prev` may be `null` at genesis,
+        // but the key must be present (it is part of the signed bytes), so we
+        // reject only when it is entirely absent.
+        if (typeof env.seq !== 'number') {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: 'v2 envelope requires `seq`',
+                path: ['seq'],
+            });
+        }
+        if (env.prev === undefined) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: 'v2 envelope requires `prev` (use `null` at genesis)',
+                path: ['prev'],
+            });
+        }
+        if (typeof env.collection !== 'string') {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: 'v2 envelope requires `collection`',
+                path: ['collection'],
+            });
+        }
+        if (typeof env.rkey !== 'string') {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: 'v2 envelope requires `rkey`',
+                path: ['rkey'],
+            });
+        }
+    }
+    else {
+        // v1 FORBIDS the v2 chain fields entirely, so a legacy envelope keeps
+        // its exact byte shape and cannot smuggle unsigned chain metadata.
+        if (env.seq !== undefined) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: 'v1 envelope must not carry `seq`',
+                path: ['seq'],
+            });
+        }
+        if (env.prev !== undefined) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: 'v1 envelope must not carry `prev`',
+                path: ['prev'],
+            });
+        }
+        if (env.collection !== undefined) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: 'v1 envelope must not carry `collection`',
+                path: ['collection'],
+            });
+        }
+        if (env.rkey !== undefined) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: 'v1 envelope must not carry `rkey`',
+                path: ['rkey'],
+            });
+        }
+    }
 });
 exports.verifiedDomainSchema = zod_1.z.object({
     domain: zod_1.z.string(),

package/dist/cjs/index.js

@@ -11,7 +11,8 @@
  * expo, no `require()` in the ESM build.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.exportBundleSchema = exports.exportAttestationSchema = exports.authMethodsResponseSchema = exports.authMethodEntrySchema = exports.domainVerificationInstructionsSchema = exports.domainVerificationRequestSchema = exports.verifiedDomainSchema = exports.signedRecordEnvelopeSchema = exports.didDocumentSchema = exports.didServiceSchema = exports.verificationMethodSchema = exports.appUserSignalIngestSchema = exports.appInterestInputSchema = exports.appEndorsementInputSchema = exports.recommendationResponseSchema = exports.recommendationItemSchema = exports.recommendationCountSchema = exports.recommendationRequestSchema = exports.recommendationSignalWeightsSchema = exports.recommendationBoostSchema = exports.recommendationExcludeTypeSchema = exports.fedcmTokenPayloadSchema = exports.sessionStatusSchema = exports.publicApplicationSchema = exports.applicationTypeSchema = exports.safeParseContract = exports.resolveUserId = exports.deviceSessionsResponseSchema = exports.deviceSessionAccountSchema = exports.currentUserResponseSchema = exports.refreshAllResponseSchema = exports.refreshAllAccountSchema = exports.userProfileUpdateSchema = exports.userResponseSchema = exports.userNameSchema = void 0;
+exports.verifiableCredentialResponseSchema = exports.credentialRecordSchema = exports.vouchResultSchema = exports.personhoodStatusResultSchema = exports.personhoodBreakdownSchema = exports.personhoodVouchRecordSchema = exports.validationVoteResultSchema = exports.validationRequestSummarySchema = exports.validationOpenResultSchema = exports.validationOpenRequestSchema = exports.validationVerdictRecordSchema = exports.realLifeAttestationResultSchema = exports.realLifeAttestationRecordSchema = exports.signedPublicCardSchema = exports.publicCardSchema = exports.exportBundleSchema = exports.exportAttestationSchema = exports.authMethodsResponseSchema = exports.authMethodEntrySchema = exports.domainVerificationInstructionsSchema = exports.domainVerificationRequestSchema = exports.verifiedDomainSchema = exports.signedRecordEnvelopeSchema = exports.didDocumentSchema = exports.didServiceSchema = exports.verificationMethodSchema = exports.appUserSignalIngestSchema = exports.appInterestInputSchema = exports.appEndorsementInputSchema = exports.recommendationResponseSchema = exports.recommendationItemSchema = exports.recommendationCountSchema = exports.recommendationRequestSchema = exports.recommendationSignalWeightsSchema = exports.recommendationBoostSchema = exports.recommendationExcludeTypeSchema = exports.fedcmTokenPayloadSchema = exports.sessionStatusSchema = exports.publicApplicationSchema = exports.applicationTypeSchema = exports.safeParseContract = exports.resolveUserId = exports.deviceSessionsResponseSchema = exports.deviceSessionAccountSchema = exports.currentUserResponseSchema = exports.refreshAllResponseSchema = exports.refreshAllAccountSchema = exports.userProfileUpdateSchema = exports.userResponseSchema = exports.userNameSchema = void 0;
+exports.linkPreviewResponseSchema = exports.linkPreviewBatchResponseSchema = exports.linkPreviewBatchRequestSchema = exports.linkPreviewSchema = exports.credentialVerifyResultSchema = exports.credentialListResultSchema = exports.credentialIssueResultSchema = void 0;
 var userResponse_1 = require("./userResponse");
 // Schemas
 Object.defineProperty(exports, "userNameSchema", { enumerable: true, get: function () { return userResponse_1.userNameSchema; } });
@@ -58,3 +59,30 @@ Object.defineProperty(exports, "authMethodEntrySchema", { enumerable: true, get:
 Object.defineProperty(exports, "authMethodsResponseSchema", { enumerable: true, get: function () { return identity_1.authMethodsResponseSchema; } });
 Object.defineProperty(exports, "exportAttestationSchema", { enumerable: true, get: function () { return identity_1.exportAttestationSchema; } });
 Object.defineProperty(exports, "exportBundleSchema", { enumerable: true, get: function () { return identity_1.exportBundleSchema; } });
+var civic_1 = require("./civic");
+// Schemas
+Object.defineProperty(exports, "publicCardSchema", { enumerable: true, get: function () { return civic_1.publicCardSchema; } });
+Object.defineProperty(exports, "signedPublicCardSchema", { enumerable: true, get: function () { return civic_1.signedPublicCardSchema; } });
+Object.defineProperty(exports, "realLifeAttestationRecordSchema", { enumerable: true, get: function () { return civic_1.realLifeAttestationRecordSchema; } });
+Object.defineProperty(exports, "realLifeAttestationResultSchema", { enumerable: true, get: function () { return civic_1.realLifeAttestationResultSchema; } });
+Object.defineProperty(exports, "validationVerdictRecordSchema", { enumerable: true, get: function () { return civic_1.validationVerdictRecordSchema; } });
+Object.defineProperty(exports, "validationOpenRequestSchema", { enumerable: true, get: function () { return civic_1.validationOpenRequestSchema; } });
+Object.defineProperty(exports, "validationOpenResultSchema", { enumerable: true, get: function () { return civic_1.validationOpenResultSchema; } });
+Object.defineProperty(exports, "validationRequestSummarySchema", { enumerable: true, get: function () { return civic_1.validationRequestSummarySchema; } });
+Object.defineProperty(exports, "validationVoteResultSchema", { enumerable: true, get: function () { return civic_1.validationVoteResultSchema; } });
+Object.defineProperty(exports, "personhoodVouchRecordSchema", { enumerable: true, get: function () { return civic_1.personhoodVouchRecordSchema; } });
+Object.defineProperty(exports, "personhoodBreakdownSchema", { enumerable: true, get: function () { return civic_1.personhoodBreakdownSchema; } });
+Object.defineProperty(exports, "personhoodStatusResultSchema", { enumerable: true, get: function () { return civic_1.personhoodStatusResultSchema; } });
+Object.defineProperty(exports, "vouchResultSchema", { enumerable: true, get: function () { return civic_1.vouchResultSchema; } });
+// Verifiable Credentials (Fase 4 — NEW)
+Object.defineProperty(exports, "credentialRecordSchema", { enumerable: true, get: function () { return civic_1.credentialRecordSchema; } });
+Object.defineProperty(exports, "verifiableCredentialResponseSchema", { enumerable: true, get: function () { return civic_1.verifiableCredentialResponseSchema; } });
+Object.defineProperty(exports, "credentialIssueResultSchema", { enumerable: true, get: function () { return civic_1.credentialIssueResultSchema; } });
+Object.defineProperty(exports, "credentialListResultSchema", { enumerable: true, get: function () { return civic_1.credentialListResultSchema; } });
+Object.defineProperty(exports, "credentialVerifyResultSchema", { enumerable: true, get: function () { return civic_1.credentialVerifyResultSchema; } });
+var links_1 = require("./links");
+// Schemas
+Object.defineProperty(exports, "linkPreviewSchema", { enumerable: true, get: function () { return links_1.linkPreviewSchema; } });
+Object.defineProperty(exports, "linkPreviewBatchRequestSchema", { enumerable: true, get: function () { return links_1.linkPreviewBatchRequestSchema; } });
+Object.defineProperty(exports, "linkPreviewBatchResponseSchema", { enumerable: true, get: function () { return links_1.linkPreviewBatchResponseSchema; } });
+Object.defineProperty(exports, "linkPreviewResponseSchema", { enumerable: true, get: function () { return links_1.linkPreviewResponseSchema; } });

package/dist/cjs/links.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Link-preview / unfurl API contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of Oxy's link-preview ("unfurl")
+ * resolution surface: the single `GET` lookup and the `POST` batch lookup that
+ * every app calls through the SDK so apps stop duplicating their own
+ * link-metadata fetching. The API validates its OUTPUT against these schemas;
+ * every consumer (`@oxyhq/core`'s link mixin and the apps that call it)
+ * validates its INPUT against the same definitions, so producer and consumers
+ * cannot drift.
+ *
+ * Design anchors:
+ *  - Oxy owns resolution. The `image` (and `favicon`) URLs a preview carries are
+ *    re-hosted on Oxy media (`cloud.oxy.so/<fileId>`), never raw remote URLs —
+ *    apps render them directly with no per-app proxy.
+ *  - Resolution is best-effort and asynchronous. A preview is `'resolved'` once
+ *    metadata is materialised, `'pending'` while a first-seen URL is being
+ *    fetched in the background, or `'empty'` when the target yielded no usable
+ *    metadata. `resolvedAt` (ISO datetime) is present only once `'resolved'`.
+ *  - The batch response is keyed by the REQUESTED url (the exact string the
+ *    caller sent), not the canonical/final URL, so a caller can always look its
+ *    own input back up; the canonical URL lives on `LinkPreview.url`.
+ *
+ * The `LinkPreview` / `LinkPreviewBatchResponse` exports are declared as explicit
+ * `interface`s (with their runtime schemas annotated `z.ZodType<Interface>`),
+ * following the same rationale as `UserNameResponse` in `./userResponse`: a
+ * `z.infer<>` of a nested-object schema can degrade to `{}` under a consumer's
+ * `moduleResolution: "node"` (node10) resolution. A literal interface emits the
+ * field types verbatim in the `.d.ts` and survives BOTH `node` and `bundler`
+ * resolution. The flat batch-request schema (no nested-object hazard) is inferred
+ * via `z.infer<>`.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.linkPreviewResponseSchema = exports.linkPreviewBatchResponseSchema = exports.linkPreviewBatchRequestSchema = exports.linkPreviewSchema = void 0;
+const zod_1 = require("zod");
+exports.linkPreviewSchema = zod_1.z.object({
+    url: zod_1.z.string(),
+    status: zod_1.z.enum(['resolved', 'pending', 'empty']),
+    title: zod_1.z.string().optional(),
+    description: zod_1.z.string().optional(),
+    image: zod_1.z.string().optional(),
+    siteName: zod_1.z.string().optional(),
+    favicon: zod_1.z.string().optional(),
+    resolvedAt: zod_1.z.string().optional(),
+});
+/* -------------------------------------------------------------------------- */
+/*  Batch request / response                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * Request body for the batch unfurl endpoint. Between 1 and 50 URLs per call;
+ * the server resolves each (returning a `'pending'` placeholder for any URL it
+ * has not seen before and is fetching in the background).
+ */
+exports.linkPreviewBatchRequestSchema = zod_1.z.object({
+    urls: zod_1.z.array(zod_1.z.string().max(2048)).min(1).max(50),
+});
+exports.linkPreviewBatchResponseSchema = zod_1.z.object({
+    data: zod_1.z.record(zod_1.z.string(), exports.linkPreviewSchema),
+});
+/**
+ * Wire shape of the single-URL unfurl lookup (`GET`) — a bare
+ * {@link LinkPreview}.
+ */
+exports.linkPreviewResponseSchema = exports.linkPreviewSchema;