@oxyhq/contracts 0.7.0 → 0.9.0

package/dist/cjs/deviceBoot.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Device-first bootstrap & token contracts (auth centralization, wave 1).
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the new device-first session
+ * bootstrap: the top-level `#oxy_boot=…` fragment the API hands back from
+ * `GET /auth/device/bootstrap`, the token bundle a boot code / web-session
+ * fast-path exchanges into, the persisted-refresh rotation, the native
+ * device-token issuance, the IdP chooser's device-resolve, and the first-party
+ * password login result (2FA arm vs. session arm). The API validates its OUTPUT
+ * against these schemas; every consumer (`@oxyhq/core`'s device-boot mixin, the
+ * SDK cold boot, the IdP chooser) validates its INPUT against the same
+ * definitions, so producer and consumers cannot drift.
+ *
+ * Design anchors (from the auth-centralization plan):
+ *  - The bootstrap fragment carries NO tokens and NO deviceId — only a
+ *    `state` echo (CSRF), a `reason`, a short-lived single-use `code`, and an
+ *    opaque `deviceToken`. Tokens are obtained by exchanging the `code` at
+ *    `POST /auth/device/exchange` (origin-bound GETDEL burn).
+ *  - Refresh is ONE rotating, single-use family shared by web and native.
+ *  - `loginResult` mirrors what `POST /auth/login` returns today
+ *    (`buildSessionAuthResponse` in the API's `session.controller.ts`): either a
+ *    2FA challenge (`{ twoFactorRequired: true, loginToken }`) or a session
+ *    payload. The session arm matches `SessionAuthResponse` EXACTLY, plus an
+ *    optional `refreshToken` the new server adds for the persisted-refresh lane.
+ *
+ * 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()`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deviceResolveResponseSchema = exports.deviceResolveRequestSchema = exports.loginResultSchema = exports.deviceTokenIssueResponseSchema = exports.tokenRefreshResponseSchema = exports.tokenRefreshRequestSchema = exports.authTokenBundleSchema = exports.deviceExchangeRequestSchema = exports.deviceBootFragmentSchema = exports.deviceBootReasonSchema = void 0;
+const zod_1 = require("zod");
+const userResponse_1 = require("./userResponse");
+/* -------------------------------------------------------------------------- */
+/*  Bootstrap fragment                                                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * Why the bootstrap hop resolved the way it did.
+ *  - `session` — the device cookie resolved an active session; a `code` is
+ *    present to exchange for tokens.
+ *  - `no_session` — the device is known but has no active session; no `code`.
+ *  - `new_device` — first contact; the cookie was just planted, no session yet.
+ */
+exports.deviceBootReasonSchema = zod_1.z.enum(['session', 'no_session', 'new_device']);
+/**
+ * The `#oxy_boot=<json>` fragment `GET /auth/device/bootstrap` appends to the
+ * `return_to` URL. Carries the CSRF `state` echo, the resolution `reason`, an
+ * optional single-use exchange `code` (present iff `reason === 'session'`), and
+ * the opaque `deviceToken`. NEVER carries tokens or a deviceId.
+ */
+exports.deviceBootFragmentSchema = zod_1.z.object({
+    v: zod_1.z.literal(1),
+    state: zod_1.z.string().min(1).max(256),
+    reason: exports.deviceBootReasonSchema,
+    code: zod_1.z.string().min(20).max(128).optional(),
+    deviceToken: zod_1.z.string().min(20).max(512),
+});
+/* -------------------------------------------------------------------------- */
+/*  Boot-code exchange                                                        */
+/* -------------------------------------------------------------------------- */
+/** Request body for `POST /auth/device/exchange` — the single-use boot code. */
+exports.deviceExchangeRequestSchema = zod_1.z.object({
+    code: zod_1.z.string().min(20).max(128),
+});
+exports.authTokenBundleSchema = zod_1.z.object({
+    sessionId: zod_1.z.string(),
+    accessToken: zod_1.z.string(),
+    refreshToken: zod_1.z.string(),
+    expiresAt: zod_1.z.string(),
+    user: userResponse_1.userResponseSchema,
+});
+/* -------------------------------------------------------------------------- */
+/*  Refresh-token rotation (web + native, one implementation)                 */
+/* -------------------------------------------------------------------------- */
+/** Request body for `POST /auth/refresh-token` — the current refresh token. */
+exports.tokenRefreshRequestSchema = zod_1.z.object({
+    refreshToken: zod_1.z.string().min(20),
+});
+/**
+ * Wire shape of `POST /auth/refresh-token`: the rotated (single-use) family —
+ * a new access token, the next refresh token, the new access-token expiry, and
+ * the owning session id. `expiresAt` is an ISO string.
+ */
+exports.tokenRefreshResponseSchema = zod_1.z.object({
+    accessToken: zod_1.z.string(),
+    refreshToken: zod_1.z.string(),
+    expiresAt: zod_1.z.string(),
+    sessionId: zod_1.z.string(),
+});
+/* -------------------------------------------------------------------------- */
+/*  Native device-token issuance                                              */
+/* -------------------------------------------------------------------------- */
+/**
+ * Wire shape of `POST /auth/device/token` — issues (or rotates) the opaque
+ * device token for the native channel. The deviceId is taken from the bearer
+ * JWT claims server-side; only the token comes back.
+ */
+exports.deviceTokenIssueResponseSchema = zod_1.z.object({
+    deviceToken: zod_1.z.string(),
+});
+const loginTwoFactorRequiredSchema = zod_1.z.object({
+    twoFactorRequired: zod_1.z.literal(true),
+    loginToken: zod_1.z.string(),
+});
+const loginSessionResultSchema = zod_1.z.object({
+    sessionId: zod_1.z.string(),
+    deviceId: zod_1.z.string(),
+    expiresAt: zod_1.z.string(),
+    accessToken: zod_1.z.string().optional(),
+    refreshToken: zod_1.z.string().optional(),
+    user: zod_1.z.object({
+        id: zod_1.z.string(),
+        username: zod_1.z.string().optional(),
+        avatar: zod_1.z.string().optional(),
+    }),
+});
+exports.loginResultSchema = zod_1.z.union([
+    loginTwoFactorRequiredSchema,
+    loginSessionResultSchema,
+]);
+/* -------------------------------------------------------------------------- */
+/*  IdP chooser device-resolve                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * Request body for `POST /auth/device/resolve` (X-Oxy-Internal, called by the
+ * IdP chooser) — the device key the chooser read from the first-party
+ * `oxy_device` cookie.
+ */
+exports.deviceResolveRequestSchema = zod_1.z.object({
+    deviceKey: zod_1.z.string().min(20),
+});
+const deviceResolveAccountSchema = zod_1.z.object({
+    user: userResponse_1.userResponseSchema,
+    sessionId: zod_1.z.string(),
+    accessToken: zod_1.z.string(),
+    expiresAt: zod_1.z.string(),
+});
+exports.deviceResolveResponseSchema = zod_1.z.object({
+    activeAccountId: zod_1.z.string().nullable(),
+    accounts: zod_1.z.array(deviceResolveAccountSchema),
+});

package/dist/cjs/deviceSession.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deviceSessionSyncSchema = exports.activeTokenSchema = exports.deviceSessionStateSchema = exports.sessionAccountSchema = void 0;
+const zod_1 = require("zod");
+exports.sessionAccountSchema = zod_1.z.object({
+    accountId: zod_1.z.string(),
+    sessionId: zod_1.z.string(),
+    authuser: zod_1.z.number().int().nonnegative(),
+    operatedByUserId: zod_1.z.string().optional(),
+});
+exports.deviceSessionStateSchema = zod_1.z.object({
+    deviceId: zod_1.z.string(),
+    accounts: zod_1.z.array(exports.sessionAccountSchema),
+    activeAccountId: zod_1.z.string().nullable(),
+    revision: zod_1.z.number().int().nonnegative(),
+    updatedAt: zod_1.z.number(),
+});
+exports.activeTokenSchema = zod_1.z.object({
+    accessToken: zod_1.z.string(),
+    expiresAt: zod_1.z.string(),
+});
+exports.deviceSessionSyncSchema = zod_1.z.object({
+    state: exports.deviceSessionStateSchema,
+    activeToken: exports.activeTokenSchema.nullable(),
+});

package/dist/cjs/fedcmToken.js

@@ -45,5 +45,12 @@ exports.fedcmTokenPayloadSchema = zod_1.z
     exp: zod_1.z.number().optional(),
     iat: zod_1.z.number().optional(),
     nonce: zod_1.z.string().optional(),
+    /**
+     * An explicit central deviceId minted by the IdP, threaded through so the
+     * RP session can inherit a unified device id instead of deriving one from
+     * the (userId, RP origin) stableDeviceKey. Optional and additive — omitted
+     * tokens fall back to the existing stableDeviceKey/UA-IP derivation.
+     */
+    deviceId: zod_1.z.string().optional(),
 })
     .passthrough();

package/dist/cjs/identity.js

@@ -41,12 +41,27 @@
 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 = void 0;
 const zod_1 = require("zod");
-exports.verificationMethodSchema = zod_1.z.object({
+// The option schemas are left UN-annotated so they keep their concrete
+// `ZodObject` type — `z.discriminatedUnion` requires object options and an
+// explicit `z.ZodType<>` annotation would erase the shape it discriminates on.
+// `z.object` already infers each option's type exactly (id/type/controller +
+// the key field), so the union is structurally `VerificationMethod`.
+const secp256k1VerificationMethodSchema = zod_1.z.object({
     id: zod_1.z.string(),
     type: zod_1.z.literal('EcdsaSecp256k1VerificationKey2019'),
     controller: zod_1.z.string(),
     publicKeyHex: zod_1.z.string(),
 });
+const multikeyVerificationMethodSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    type: zod_1.z.literal('Multikey'),
+    controller: zod_1.z.string(),
+    publicKeyMultibase: zod_1.z.string(),
+});
+exports.verificationMethodSchema = zod_1.z.discriminatedUnion('type', [
+    secp256k1VerificationMethodSchema,
+    multikeyVerificationMethodSchema,
+]);
 exports.didServiceSchema = zod_1.z.object({
     id: zod_1.z.string(),
     type: zod_1.z.string(),

package/dist/cjs/index.js

@@ -11,8 +11,8 @@
  * expo, no `require()` in the ESM build.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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.logPageResponseSchema = exports.chainHeadResponseSchema = exports.oxySignedRecordTypeSchema = 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 = exports.verifiableCredentialResponseSchema = exports.credentialRecordSchema = exports.vouchResultSchema = void 0;
+exports.validationVoteResultSchema = exports.validationRequestSummarySchema = exports.validationOpenResultSchema = exports.validationOpenRequestSchema = exports.validationVerdictRecordSchema = exports.realLifeAttestationResultSchema = exports.realLifeAttestationRecordSchema = exports.signedPublicCardSchema = exports.publicCardSchema = exports.logPageResponseSchema = exports.chainHeadResponseSchema = exports.oxySignedRecordTypeSchema = exports.exportBundleSchema = exports.exportAttestationSchema = exports.authMethodsResponseSchema = exports.authMethodEntrySchema = exports.domainVerificationInstructionsSchema = exports.domainVerificationRequestSchema = exports.verifiedDomainSchema = exports.signedRecordEnvelopeSchema = exports.didDocumentSchema = exports.didServiceSchema = exports.verificationMethodSchema = exports.appAffinityEventsIngestSchema = exports.appAffinityEventSchema = exports.appAffinityEventTypeSchema = 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.deviceResolveResponseSchema = exports.deviceResolveRequestSchema = exports.loginResultSchema = exports.deviceTokenIssueResponseSchema = exports.tokenRefreshResponseSchema = exports.tokenRefreshRequestSchema = exports.authTokenBundleSchema = exports.deviceExchangeRequestSchema = exports.deviceBootFragmentSchema = exports.deviceBootReasonSchema = exports.deviceSessionSyncSchema = exports.activeTokenSchema = exports.deviceSessionStateSchema = exports.sessionAccountSchema = exports.linkPreviewResponseSchema = exports.linkPreviewBatchResponseSchema = exports.linkPreviewBatchRequestSchema = exports.linkPreviewSchema = exports.credentialVerifyResultSchema = exports.credentialListResultSchema = exports.credentialIssueResultSchema = exports.verifiableCredentialResponseSchema = exports.credentialRecordSchema = exports.vouchResultSchema = exports.personhoodStatusResultSchema = exports.personhoodBreakdownSchema = exports.personhoodVouchRecordSchema = void 0;
 var userResponse_1 = require("./userResponse");
 // Schemas
 Object.defineProperty(exports, "userNameSchema", { enumerable: true, get: function () { return userResponse_1.userNameSchema; } });
@@ -46,6 +46,9 @@ Object.defineProperty(exports, "recommendationResponseSchema", { enumerable: tru
 Object.defineProperty(exports, "appEndorsementInputSchema", { enumerable: true, get: function () { return recommendations_1.appEndorsementInputSchema; } });
 Object.defineProperty(exports, "appInterestInputSchema", { enumerable: true, get: function () { return recommendations_1.appInterestInputSchema; } });
 Object.defineProperty(exports, "appUserSignalIngestSchema", { enumerable: true, get: function () { return recommendations_1.appUserSignalIngestSchema; } });
+Object.defineProperty(exports, "appAffinityEventTypeSchema", { enumerable: true, get: function () { return recommendations_1.appAffinityEventTypeSchema; } });
+Object.defineProperty(exports, "appAffinityEventSchema", { enumerable: true, get: function () { return recommendations_1.appAffinityEventSchema; } });
+Object.defineProperty(exports, "appAffinityEventsIngestSchema", { enumerable: true, get: function () { return recommendations_1.appAffinityEventsIngestSchema; } });
 var identity_1 = require("./identity");
 // Schemas
 Object.defineProperty(exports, "verificationMethodSchema", { enumerable: true, get: function () { return identity_1.verificationMethodSchema; } });
@@ -93,3 +96,20 @@ Object.defineProperty(exports, "linkPreviewSchema", { enumerable: true, get: fun
 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; } });
+var deviceSession_1 = require("./deviceSession");
+Object.defineProperty(exports, "sessionAccountSchema", { enumerable: true, get: function () { return deviceSession_1.sessionAccountSchema; } });
+Object.defineProperty(exports, "deviceSessionStateSchema", { enumerable: true, get: function () { return deviceSession_1.deviceSessionStateSchema; } });
+Object.defineProperty(exports, "activeTokenSchema", { enumerable: true, get: function () { return deviceSession_1.activeTokenSchema; } });
+Object.defineProperty(exports, "deviceSessionSyncSchema", { enumerable: true, get: function () { return deviceSession_1.deviceSessionSyncSchema; } });
+var deviceBoot_1 = require("./deviceBoot");
+// Schemas
+Object.defineProperty(exports, "deviceBootReasonSchema", { enumerable: true, get: function () { return deviceBoot_1.deviceBootReasonSchema; } });
+Object.defineProperty(exports, "deviceBootFragmentSchema", { enumerable: true, get: function () { return deviceBoot_1.deviceBootFragmentSchema; } });
+Object.defineProperty(exports, "deviceExchangeRequestSchema", { enumerable: true, get: function () { return deviceBoot_1.deviceExchangeRequestSchema; } });
+Object.defineProperty(exports, "authTokenBundleSchema", { enumerable: true, get: function () { return deviceBoot_1.authTokenBundleSchema; } });
+Object.defineProperty(exports, "tokenRefreshRequestSchema", { enumerable: true, get: function () { return deviceBoot_1.tokenRefreshRequestSchema; } });
+Object.defineProperty(exports, "tokenRefreshResponseSchema", { enumerable: true, get: function () { return deviceBoot_1.tokenRefreshResponseSchema; } });
+Object.defineProperty(exports, "deviceTokenIssueResponseSchema", { enumerable: true, get: function () { return deviceBoot_1.deviceTokenIssueResponseSchema; } });
+Object.defineProperty(exports, "loginResultSchema", { enumerable: true, get: function () { return deviceBoot_1.loginResultSchema; } });
+Object.defineProperty(exports, "deviceResolveRequestSchema", { enumerable: true, get: function () { return deviceBoot_1.deviceResolveRequestSchema; } });
+Object.defineProperty(exports, "deviceResolveResponseSchema", { enumerable: true, get: function () { return deviceBoot_1.deviceResolveResponseSchema; } });

package/dist/cjs/recommendations.js

@@ -12,7 +12,7 @@
  * / expo, ESM-safe).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.appUserSignalIngestSchema = exports.appInterestInputSchema = exports.appEndorsementInputSchema = exports.recommendationResponseSchema = exports.recommendationItemSchema = exports.recommendationCountSchema = exports.recommendationRequestSchema = exports.recommendationSignalWeightsSchema = exports.recommendationBoostSchema = exports.recommendationExcludeTypeSchema = void 0;
+exports.appAffinityEventsIngestSchema = exports.appAffinityEventSchema = exports.appAffinityEventTypeSchema = exports.appUserSignalIngestSchema = exports.appInterestInputSchema = exports.appEndorsementInputSchema = exports.recommendationResponseSchema = exports.recommendationItemSchema = exports.recommendationCountSchema = exports.recommendationRequestSchema = exports.recommendationSignalWeightsSchema = exports.recommendationBoostSchema = exports.recommendationExcludeTypeSchema = void 0;
 const zod_1 = require("zod");
 const userResponse_1 = require("./userResponse");
 /** User-type filters a caller may exclude from the recommendation surface. */
@@ -46,6 +46,7 @@ exports.recommendationSignalWeightsSchema = zod_1.z
     interest: zod_1.z.number().min(0).max(10).optional(),
     appBoost: zod_1.z.number().min(0).max(10).optional(),
     repCandidate: zod_1.z.number().min(0).max(10).optional(),
+    affinity: zod_1.z.number().min(0).max(10).optional(),
 })
     .partial();
 /**
@@ -123,3 +124,45 @@ exports.appUserSignalIngestSchema = zod_1.z
     interests: zod_1.z.array(exports.appInterestInputSchema).max(500).optional(),
 })
     .refine((value) => (value.endorsements?.length ?? 0) > 0 || (value.interests?.length ?? 0) > 0, { message: 'At least one of endorsements or interests must be non-empty' });
+/**
+ * The directed interaction types a consuming app may report between two users.
+ * Each type carries a server-side default weight (see the API's
+ * `AFFINITY_EVENT_WEIGHTS`); a caller may override the applied weight per event.
+ */
+exports.appAffinityEventTypeSchema = zod_1.z.enum([
+    'like',
+    'reply',
+    'boost',
+    'follow',
+    'mention',
+    'profile_view',
+    'quote',
+    'repost',
+]);
+/**
+ * One directed interaction event: `fromUserId` interacted with `toUserId`
+ * (`type`) at `occurredAt`. The Oxy affinity-graph folds these into a per-app,
+ * time-decayed directed affinity edge (`fromUserId → toUserId`).
+ *
+ * - `weight` (optional) overrides the per-type default weight for this event.
+ * - `occurredAt` (optional, ISO) is the event time; absent means "now" at ingest.
+ * - `eventId` (optional) makes an event idempotent — a repeated `eventId` for the
+ *   same application is folded at most once (bounded dedup window).
+ */
+exports.appAffinityEventSchema = zod_1.z.object({
+    fromUserId: zod_1.z.string().trim().min(1),
+    toUserId: zod_1.z.string().trim().min(1),
+    type: exports.appAffinityEventTypeSchema,
+    weight: zod_1.z.number().min(0).max(100).optional(),
+    occurredAt: zod_1.z.string().datetime().optional(),
+    eventId: zod_1.z.string().trim().min(1).max(200).optional(),
+});
+/**
+ * Request body for `POST /app-signals/events` (service token, `signals:write`).
+ *
+ * A non-empty batch (1..1000) of directed interaction events for the requesting
+ * application. Self-edges (`fromUserId === toUserId`) are dropped server-side.
+ */
+exports.appAffinityEventsIngestSchema = zod_1.z.object({
+    events: zod_1.z.array(exports.appAffinityEventSchema).min(1).max(1000),
+});