@oxyhq/contracts 0.7.0 → 0.9.0

package/dist/esm/deviceBoot.js

@@ -0,0 +1,145 @@
+/**
+ * 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()`).
+ */
+import { z } from 'zod';
+import { userResponseSchema } from './userResponse.js';
+/* -------------------------------------------------------------------------- */
+/*  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.
+ */
+export const deviceBootReasonSchema = 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.
+ */
+export const deviceBootFragmentSchema = z.object({
+    v: z.literal(1),
+    state: z.string().min(1).max(256),
+    reason: deviceBootReasonSchema,
+    code: z.string().min(20).max(128).optional(),
+    deviceToken: z.string().min(20).max(512),
+});
+/* -------------------------------------------------------------------------- */
+/*  Boot-code exchange                                                        */
+/* -------------------------------------------------------------------------- */
+/** Request body for `POST /auth/device/exchange` — the single-use boot code. */
+export const deviceExchangeRequestSchema = z.object({
+    code: z.string().min(20).max(128),
+});
+export const authTokenBundleSchema = z.object({
+    sessionId: z.string(),
+    accessToken: z.string(),
+    refreshToken: z.string(),
+    expiresAt: z.string(),
+    user: userResponseSchema,
+});
+/* -------------------------------------------------------------------------- */
+/*  Refresh-token rotation (web + native, one implementation)                 */
+/* -------------------------------------------------------------------------- */
+/** Request body for `POST /auth/refresh-token` — the current refresh token. */
+export const tokenRefreshRequestSchema = z.object({
+    refreshToken: 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.
+ */
+export const tokenRefreshResponseSchema = z.object({
+    accessToken: z.string(),
+    refreshToken: z.string(),
+    expiresAt: z.string(),
+    sessionId: 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.
+ */
+export const deviceTokenIssueResponseSchema = z.object({
+    deviceToken: z.string(),
+});
+const loginTwoFactorRequiredSchema = z.object({
+    twoFactorRequired: z.literal(true),
+    loginToken: z.string(),
+});
+const loginSessionResultSchema = z.object({
+    sessionId: z.string(),
+    deviceId: z.string(),
+    expiresAt: z.string(),
+    accessToken: z.string().optional(),
+    refreshToken: z.string().optional(),
+    user: z.object({
+        id: z.string(),
+        username: z.string().optional(),
+        avatar: z.string().optional(),
+    }),
+});
+export const loginResultSchema = 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.
+ */
+export const deviceResolveRequestSchema = z.object({
+    deviceKey: z.string().min(20),
+});
+const deviceResolveAccountSchema = z.object({
+    user: userResponseSchema,
+    sessionId: z.string(),
+    accessToken: z.string(),
+    expiresAt: z.string(),
+});
+export const deviceResolveResponseSchema = z.object({
+    activeAccountId: z.string().nullable(),
+    accounts: z.array(deviceResolveAccountSchema),
+});

package/dist/esm/deviceSession.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export const sessionAccountSchema = z.object({
+    accountId: z.string(),
+    sessionId: z.string(),
+    authuser: z.number().int().nonnegative(),
+    operatedByUserId: z.string().optional(),
+});
+export const deviceSessionStateSchema = z.object({
+    deviceId: z.string(),
+    accounts: z.array(sessionAccountSchema),
+    activeAccountId: z.string().nullable(),
+    revision: z.number().int().nonnegative(),
+    updatedAt: z.number(),
+});
+export const activeTokenSchema = z.object({
+    accessToken: z.string(),
+    expiresAt: z.string(),
+});
+export const deviceSessionSyncSchema = z.object({
+    state: deviceSessionStateSchema,
+    activeToken: activeTokenSchema.nullable(),
+});

package/dist/esm/fedcmToken.js

@@ -42,5 +42,12 @@ export const fedcmTokenPayloadSchema = z
     exp: z.number().optional(),
     iat: z.number().optional(),
     nonce: 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: z.string().optional(),
 })
     .passthrough();

package/dist/esm/identity.js

@@ -38,12 +38,27 @@
  * `require()`).
  */
 import { z } from 'zod';
-export const verificationMethodSchema = 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 = z.object({
     id: z.string(),
     type: z.literal('EcdsaSecp256k1VerificationKey2019'),
     controller: z.string(),
     publicKeyHex: z.string(),
 });
+const multikeyVerificationMethodSchema = z.object({
+    id: z.string(),
+    type: z.literal('Multikey'),
+    controller: z.string(),
+    publicKeyMultibase: z.string(),
+});
+export const verificationMethodSchema = z.discriminatedUnion('type', [
+    secp256k1VerificationMethodSchema,
+    multikeyVerificationMethodSchema,
+]);
 export const didServiceSchema = z.object({
     id: z.string(),
     type: z.string(),

package/dist/esm/index.js

@@ -22,7 +22,7 @@ export {
 fedcmTokenPayloadSchema, } from './fedcmToken.js';
 export { 
 // Schemas
-recommendationExcludeTypeSchema, recommendationBoostSchema, recommendationSignalWeightsSchema, recommendationRequestSchema, recommendationCountSchema, recommendationItemSchema, recommendationResponseSchema, appEndorsementInputSchema, appInterestInputSchema, appUserSignalIngestSchema, } from './recommendations.js';
+recommendationExcludeTypeSchema, recommendationBoostSchema, recommendationSignalWeightsSchema, recommendationRequestSchema, recommendationCountSchema, recommendationItemSchema, recommendationResponseSchema, appEndorsementInputSchema, appInterestInputSchema, appUserSignalIngestSchema, appAffinityEventTypeSchema, appAffinityEventSchema, appAffinityEventsIngestSchema, } from './recommendations.js';
 export { 
 // Schemas
 verificationMethodSchema, didServiceSchema, didDocumentSchema, signedRecordEnvelopeSchema, verifiedDomainSchema, domainVerificationRequestSchema, domainVerificationInstructionsSchema, authMethodEntrySchema, authMethodsResponseSchema, exportAttestationSchema, exportBundleSchema, } from './identity.js';
@@ -40,3 +40,7 @@ credentialRecordSchema, verifiableCredentialResponseSchema, credentialIssueResul
 export { 
 // Schemas
 linkPreviewSchema, linkPreviewBatchRequestSchema, linkPreviewBatchResponseSchema, linkPreviewResponseSchema, } from './links.js';
+export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, } from './deviceSession.js';
+export { 
+// Schemas
+deviceBootReasonSchema, deviceBootFragmentSchema, deviceExchangeRequestSchema, authTokenBundleSchema, tokenRefreshRequestSchema, tokenRefreshResponseSchema, deviceTokenIssueResponseSchema, loginResultSchema, deviceResolveRequestSchema, deviceResolveResponseSchema, } from './deviceBoot.js';

package/dist/esm/recommendations.js

@@ -43,6 +43,7 @@ export const recommendationSignalWeightsSchema = z
     interest: z.number().min(0).max(10).optional(),
     appBoost: z.number().min(0).max(10).optional(),
     repCandidate: z.number().min(0).max(10).optional(),
+    affinity: z.number().min(0).max(10).optional(),
 })
     .partial();
 /**
@@ -120,3 +121,45 @@ export const appUserSignalIngestSchema = z
     interests: z.array(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.
+ */
+export const appAffinityEventTypeSchema = 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).
+ */
+export const appAffinityEventSchema = z.object({
+    fromUserId: z.string().trim().min(1),
+    toUserId: z.string().trim().min(1),
+    type: appAffinityEventTypeSchema,
+    weight: z.number().min(0).max(100).optional(),
+    occurredAt: z.string().datetime().optional(),
+    eventId: 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.
+ */
+export const appAffinityEventsIngestSchema = z.object({
+    events: z.array(appAffinityEventSchema).min(1).max(1000),
+});