@oxyhq/contracts 0.11.0 → 0.13.0

package/dist/esm/deviceBoot.js

@@ -1,27 +1,15 @@
 /**
- * Device-first bootstrap & token contracts (auth centralization, wave 1).
+ * First-party login result contract.
  *
- * 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.
+ * SINGLE SOURCE OF TRUTH for the first-party password login result (2FA arm vs.
+ * session arm). The API validates its OUTPUT against this schema; every consumer
+ * (`@oxyhq/core`'s auth mixin) validates its INPUT against the same definition,
+ * 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.
+ * The device transport is `deviceId` + `deviceSecret` + `POST /session/device/token`
+ * (see `deviceSession.ts`). The legacy cookie/bootstrap/refresh-family lanes were
+ * removed in the zero-cookie cutover — nothing here carries a refresh token or a
+ * boot fragment.
  *
  * Nested-object response shapes are declared as explicit `interface`s with the
  * runtime schema annotated `z.ZodType<Interface>` — the same rationale as
@@ -34,127 +22,25 @@
  * `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`, the
- * opaque `deviceToken`, and — ONLY on the `session` arm — the single-use
- * exchange `code`. NEVER carries tokens or a deviceId.
- *
- * Discriminated on `reason` so the code↔reason coupling is enforced by the
- * schema, not by the consumer: the `session` arm REQUIRES `code`, and the
- * `no_session` / `new_device` arms omit it (a stray `code` on those arms is
- * stripped). A `session` fragment WITHOUT a code therefore fails to parse and
- * is treated as "no usable fragment" rather than half-processed.
- */
-const deviceBootFragmentBase = {
-    v: z.literal(1),
-    state: z.string().min(1).max(256),
-    deviceToken: z.string().min(20).max(512),
-};
-export const deviceBootFragmentSchema = z.discriminatedUnion('reason', [
-    z.object({
-        ...deviceBootFragmentBase,
-        reason: z.literal('session'),
-        code: z.string().min(20).max(128),
-    }),
-    z.object({
-        ...deviceBootFragmentBase,
-        reason: z.literal('no_session'),
-    }),
-    z.object({
-        ...deviceBootFragmentBase,
-        reason: z.literal('new_device'),
-    }),
-]);
-/* -------------------------------------------------------------------------- */
-/*  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,
-});
-// Internal (unexported) arm schemas — PLAIN `z.object` literals (no
-// `z.ZodType<>` annotation) so `z.discriminatedUnion` can introspect the
-// `reason` discriminator. The node10 `.d.ts`-degradation safety comes from the
-// EXPORTED symbols instead: the public types are explicit interfaces
-// (`WebSessionSession` / `WebSessionNoSession` / `WebSessionResult`) and the
-// exported schema is annotated `z.ZodType<WebSessionResult>` below, so the
-// emitted declaration states the shape literally rather than a degradable
-// `z.infer<>` of the nested `session` object.
-const webSessionSessionSchema = z.object({
-    reason: z.literal('session'),
-    session: authTokenBundleSchema,
-    deviceToken: z.string().min(1),
-});
-const webSessionNoSessionSchema = z.object({
-    reason: z.enum(['no_session', 'new_device']),
-    deviceToken: z.string().min(1),
-});
-// Discriminated on `reason` — a true `discriminatedUnion` (not `z.union`): it
-// dispatches on the discriminator instead of sequentially probing each arm,
-// giving precise per-arm errors.
-export const webSessionResultSchema = z.discriminatedUnion('reason', [
-    webSessionSessionSchema,
-    webSessionNoSessionSchema,
-]);
-/* -------------------------------------------------------------------------- */
-/*  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 securityAlertSchema = z.object({
+    message: z.string(),
+    anomalies: z.array(z.object({
+        type: z.string(),
+        reason: z.string(),
+        details: z.string().optional(),
+    })),
+});
 const loginSessionResultSchema = z.object({
     sessionId: z.string(),
     deviceId: z.string(),
     expiresAt: z.string(),
     accessToken: z.string().optional(),
-    refreshToken: z.string().optional(),
+    deviceSecret: z.string().optional(),
+    securityAlert: securityAlertSchema.optional(),
     user: z.object({
         id: z.string(),
         username: z.string().optional(),
@@ -165,24 +51,3 @@ 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

@@ -20,3 +20,30 @@ export const deviceSessionSyncSchema = z.object({
     state: deviceSessionStateSchema,
     activeToken: activeTokenSchema.nullable(),
 });
+/* -------------------------------------------------------------------------- */
+/*  Device-secret token mint (phase 2c — zero-cookie transport)               */
+/* -------------------------------------------------------------------------- */
+/**
+ * Request body for `POST /session/device/token` — the client presents the
+ * `deviceId` it stored first-party plus the opaque `deviceSecret`. NO bearer:
+ * possession of the secret IS the proof of device ownership. The server matches
+ * `sha256(deviceSecret)` against the device's stored `secretHash` (constant-time)
+ * and mints a short access token for the device's active account.
+ */
+export const deviceTokenMintRequestSchema = z.object({
+    deviceId: z.string().min(1),
+    deviceSecret: z.string().min(1),
+});
+/**
+ * Wire shape of a successful `POST /session/device/token`: the freshly-minted
+ * short access token for the active account, its expiry, the NEXT rotating
+ * device secret the client must persist (rotation-in-use — the presented secret
+ * stays valid for a short grace so multi-tab races don't lock out), and the
+ * projected device-session state.
+ */
+export const deviceTokenMintResponseSchema = z.object({
+    accessToken: z.string(),
+    expiresAt: z.string(),
+    nextDeviceSecret: z.string(),
+    state: deviceSessionStateSchema,
+});

package/dist/esm/index.js

@@ -40,7 +40,7 @@ credentialRecordSchema, verifiableCredentialResponseSchema, credentialIssueResul
 export { 
 // Schemas
 linkPreviewSchema, linkPreviewBatchRequestSchema, linkPreviewBatchResponseSchema, linkPreviewResponseSchema, } from './links.js';
-export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, } from './deviceSession.js';
+export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, } from './deviceSession.js';
 export { 
 // Schemas
-deviceBootReasonSchema, deviceBootFragmentSchema, deviceExchangeRequestSchema, authTokenBundleSchema, webSessionResultSchema, tokenRefreshRequestSchema, tokenRefreshResponseSchema, deviceTokenIssueResponseSchema, loginResultSchema, deviceResolveRequestSchema, deviceResolveResponseSchema, } from './deviceBoot.js';
+loginResultSchema, } from './deviceBoot.js';

package/dist/esm/userResponse.js

@@ -16,8 +16,7 @@
  *
  * Faithful to the producers:
  *  - `packages/api/src/utils/userTransform.ts` `formatUserResponse` — the
- *    canonical serialization used by the device-first bootstrap/exchange
- *    endpoints (`deviceAuth.ts`), login/signup, device sessions, etc.
+ *    canonical serialization used by login/signup, device sessions, etc.
  *    Emits `id` (NOT `_id`), forwards `username` verbatim (may be absent), and
  *    emits `name` as the structured `{ first, last, full, displayName }`
  *    subdocument.