@oxyhq/contracts 0.2.1 → 0.4.0

package/dist/esm/civic.js

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

package/dist/esm/identity.js

@@ -0,0 +1,213 @@
+/**
+ * Self-sovereign identity API contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of Oxy's AtProto/Bluesky-flavoured
+ * identity & portability layer: the W3C DID document the API derives on demand,
+ * the signed-record envelope clients sign with their cryptographic key (and the
+ * server verifies), the verified-domain badge, the auth-method ↔ DID
+ * verification-method mapping, and the signed data-export ("credible exit")
+ * bundle. The API validates its OUTPUT against these schemas; every consumer
+ * (the Commons vault app, `@oxyhq/core`'s identity mixin) validates its INPUT
+ * against the same definitions, so producer and consumers cannot drift.
+ *
+ * Design anchors (from the identity-layer plan):
+ *  - DID = `did:web:oxy.so:u:<userId>` — anchored on the stable account id, NOT
+ *    the keypair. The keypair is a *verification method* that maps 1:1 to the
+ *    existing `authMethods[]`. Custodial (password-only) users get a DID
+ *    controlled solely by Oxy (`OXY_DID`); creating a Commons key upgrades them
+ *    to self-sovereign (`controller = [userDid, OXY_DID]`); fully reversible.
+ *  - Verification methods use the secp256k1 `EcdsaSecp256k1VerificationKey2019`
+ *    type with `publicKeyHex` for now (a `Multikey`/`publicKeyMultibase` form may
+ *    be added later — see the plan's open risks).
+ *  - Signed records carry an envelope whose signing input is the canonical-JSON
+ *    of every field EXCEPT `publicKey` and `signature`; `alg` is
+ *    `ES256K-DER-SHA256` (secp256k1 over the SHA-256 of the canonical bytes,
+ *    DER-encoded signature) — the same scheme `SignatureService` uses.
+ *
+ * Explicit-`interface` exports (DidDocument, SignedRecordEnvelope, ExportBundle,
+ * VerifiedDomain, AuthMethodsResponse and their sub-parts) follow the same
+ * rationale as `UserNameResponse` in `./userResponse`: a `z.infer<>` of a nested
+ * object schema can degrade under a consumer's `moduleResolution: "node"`
+ * (node10) resolution, so the load-bearing response shapes are declared as
+ * literal interfaces and the runtime schemas are annotated `z.ZodType<Interface>`
+ * — the emitted `.d.ts` then states the field types verbatim and survives BOTH
+ * `node` and `bundler` resolution. Request schemas (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';
+export const verificationMethodSchema = z.object({
+    id: z.string(),
+    type: z.literal('EcdsaSecp256k1VerificationKey2019'),
+    controller: z.string(),
+    publicKeyHex: z.string(),
+});
+export const didServiceSchema = z.object({
+    id: z.string(),
+    type: z.string(),
+    serviceEndpoint: z.string(),
+});
+export const didDocumentSchema = z.object({
+    '@context': z.array(z.string()),
+    id: z.string(),
+    controller: z.array(z.string()),
+    verificationMethod: z.array(verificationMethodSchema),
+    authentication: z.array(z.string()),
+    assertionMethod: z.array(z.string()),
+    alsoKnownAs: z.array(z.string()),
+    service: z.array(didServiceSchema),
+});
+export const signedRecordEnvelopeSchema = z
+    .object({
+    version: z.union([z.literal(1), z.literal(2)]),
+    type: z.enum([
+        'identity',
+        'profile',
+        'reputation_attestation',
+        'real_life_attestation',
+        'validation_verdict',
+        'personhood_vouch',
+        'credential',
+        'node',
+    ]),
+    subject: z.string(),
+    issuer: z.string(),
+    record: z.record(z.unknown()),
+    issuedAt: z.number(),
+    seq: z.number().int().nonnegative().optional(),
+    prev: z.string().nullable().optional(),
+    collection: z.string().min(1).optional(),
+    rkey: z.string().min(1).optional(),
+    publicKey: z.string(),
+    alg: z.literal('ES256K-DER-SHA256'),
+    signature: 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: z.ZodIssueCode.custom,
+                message: 'v2 envelope requires `seq`',
+                path: ['seq'],
+            });
+        }
+        if (env.prev === undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'v2 envelope requires `prev` (use `null` at genesis)',
+                path: ['prev'],
+            });
+        }
+        if (typeof env.collection !== 'string') {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'v2 envelope requires `collection`',
+                path: ['collection'],
+            });
+        }
+        if (typeof env.rkey !== 'string') {
+            ctx.addIssue({
+                code: 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: z.ZodIssueCode.custom,
+                message: 'v1 envelope must not carry `seq`',
+                path: ['seq'],
+            });
+        }
+        if (env.prev !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'v1 envelope must not carry `prev`',
+                path: ['prev'],
+            });
+        }
+        if (env.collection !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'v1 envelope must not carry `collection`',
+                path: ['collection'],
+            });
+        }
+        if (env.rkey !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'v1 envelope must not carry `rkey`',
+                path: ['rkey'],
+            });
+        }
+    }
+});
+export const verifiedDomainSchema = z.object({
+    domain: z.string(),
+    verifiedAt: z.union([z.string(), z.date()]),
+    method: z.enum(['dns-txt', 'well-known']),
+});
+/** Request body for `POST /identity/domains` — the domain to start verifying. */
+export const domainVerificationRequestSchema = z.object({
+    domain: z.string().trim().min(1),
+});
+/**
+ * The instructions the API returns when a domain verification is requested. The
+ * caller may prove ownership EITHER by publishing the `dns` TXT record OR by
+ * serving the `wellKnown` file; either path then satisfies
+ * `POST /identity/domains/:domain/verify`.
+ */
+export const domainVerificationInstructionsSchema = z.object({
+    domain: z.string(),
+    token: z.string(),
+    dns: z.object({
+        name: z.string(),
+        value: z.string(),
+    }),
+    wellKnown: z.object({
+        url: z.string(),
+        body: z.string(),
+    }),
+});
+export const authMethodEntrySchema = z.object({
+    type: z.enum(['identity', 'password', 'google', 'apple', 'github']),
+    linkedAt: z.union([z.string(), z.date()]),
+    verificationMethodId: z.string().optional(),
+});
+export const authMethodsResponseSchema = z.object({
+    did: z.string(),
+    methods: z.array(authMethodEntrySchema),
+});
+export const exportAttestationSchema = z.object({
+    issuer: z.string(),
+    publicKey: z.string(),
+    alg: z.literal('ES256K-DER-SHA256'),
+    signature: z.string(),
+    signedAt: z.number(),
+});
+export const exportBundleSchema = z.object({
+    '$schema': z.string(),
+    exportedAt: z.string(),
+    did: z.string(),
+    didDocument: didDocumentSchema,
+    profile: z.record(z.unknown()),
+    verifiedDomains: z.array(verifiedDomainSchema),
+    authMethods: z.array(authMethodEntrySchema),
+    signedRecords: z.array(signedRecordEnvelopeSchema),
+    appData: z.array(z.record(z.unknown())),
+    social: z.object({
+        following: z.array(z.string()),
+        followers: z.array(z.string()),
+    }),
+    attestation: exportAttestationSchema.nullable(),
+    proof: exportAttestationSchema.optional(),
+});

package/dist/esm/index.js

@@ -23,3 +23,11 @@ fedcmTokenPayloadSchema, } from './fedcmToken.js';
 export { 
 // Schemas
 recommendationExcludeTypeSchema, recommendationBoostSchema, recommendationSignalWeightsSchema, recommendationRequestSchema, recommendationCountSchema, recommendationItemSchema, recommendationResponseSchema, appEndorsementInputSchema, appInterestInputSchema, appUserSignalIngestSchema, } from './recommendations.js';
+export { 
+// Schemas
+verificationMethodSchema, didServiceSchema, didDocumentSchema, signedRecordEnvelopeSchema, verifiedDomainSchema, domainVerificationRequestSchema, domainVerificationInstructionsSchema, authMethodEntrySchema, authMethodsResponseSchema, exportAttestationSchema, exportBundleSchema, } from './identity.js';
+export { 
+// Schemas
+publicCardSchema, signedPublicCardSchema, realLifeAttestationRecordSchema, realLifeAttestationResultSchema, validationVerdictRecordSchema, validationOpenRequestSchema, validationOpenResultSchema, validationRequestSummarySchema, validationVoteResultSchema, personhoodVouchRecordSchema, personhoodBreakdownSchema, personhoodStatusResultSchema, vouchResultSchema, 
+// Verifiable Credentials (Fase 4 — NEW)
+credentialRecordSchema, verifiableCredentialResponseSchema, credentialIssueResultSchema, credentialListResultSchema, credentialVerifyResultSchema, } from './civic.js';

package/dist/esm/userResponse.js

@@ -31,6 +31,7 @@
  * `require()`).
  */
 import { z } from 'zod';
+import { verifiedDomainSchema } from './identity.js';
 export const userNameSchema = z
     .object({
     first: z.string().optional(),
@@ -63,6 +64,9 @@ export const userResponseSchema = z
     publicKey: z.string().optional(),
     username: z.string().optional(),
     email: z.string().optional(),
+    phone: z.string().optional(),
+    address: z.string().optional(),
+    birthday: z.string().optional(),
     /** Avatar file id (string) or null. */
     avatar: z.string().nullable().optional(),
     /** Named Bloom color preset (e.g. `"blue"`) or null. */
@@ -70,6 +74,17 @@ export const userResponseSchema = z
     name: userNameSchema,
     verified: z.boolean().optional(),
     language: z.string().optional(),
+    /**
+     * The account's self-sovereign identifier
+     * (`did:web:<FEDERATION_DOMAIN>:u:<userId>`). Surfaced as a `User`
+     * virtual; present on formatted DTOs once the identity layer is live.
+     */
+    did: z.string().optional(),
+    /**
+     * Proven domain-ownership badges. Each is a {@link verifiedDomainSchema}
+     * entry; present only when the account has verified at least one domain.
+     */
+    verifiedDomains: z.array(verifiedDomainSchema).optional(),
 })
     .passthrough();
 export const userProfileUpdateSchema = z
@@ -86,6 +101,9 @@ export const userProfileUpdateSchema = z
     color: z.string().nullable().optional(),
     bio: z.string().optional(),
     description: z.string().optional(),
+    phone: z.string().optional(),
+    address: z.string().optional(),
+    birthday: z.string().optional(),
     location: z.string().optional(),
     locations: z.array(z.unknown()).optional(),
     links: z.array(z.string()).optional(),