@oxyhq/contracts 0.14.0 → 0.14.2

package/dist/esm/deviceSession.js

@@ -69,3 +69,44 @@ export const deviceHubTicketRedeemResponseSchema = z.object({
     deviceId: z.string().min(1),
     deviceSecret: z.string().min(1),
 });
+/* -------------------------------------------------------------------------- */
+/*  Instant cross-app session sync (token-free socket signal)                 */
+/* -------------------------------------------------------------------------- */
+/**
+ * Name of the token-free Socket.IO event emitted to room `user:<userId>` on
+ * every DeviceSession mutation that changes what is signed in for that user.
+ *
+ * This is a pure SIGNAL — it carries NO access token, NO deviceSecret and NO
+ * account bodies. A client that receives it re-fetches its authenticated
+ * session/account state (`GET /session/device/state`, `GET /accounts`). Unlike
+ * `session_state` (scoped to `device:<deviceId>`, i.e. a single origin), this
+ * reaches ALL of a user's connected sockets across their devices/origins so
+ * every Oxy app reflects an add / switch / signout instantly.
+ */
+export const SESSION_ACCOUNTS_CHANGED_EVENT = 'session_accounts_changed';
+/**
+ * Why the signed-in set changed:
+ *  - `login`   — a brand-new session was minted for the user (QR / cross-app authorize)
+ *  - `add`     — an account was registered onto a device set
+ *  - `switch`  — the active account on a device changed
+ *  - `signout` — one or all accounts were signed out of a device
+ *  - `revoke`  — a dead/revoked account was healed out of a device set
+ */
+export const sessionAccountsChangedReasonSchema = z.enum([
+    'login',
+    'add',
+    'switch',
+    'signout',
+    'revoke',
+]);
+/**
+ * Payload of {@link SESSION_ACCOUNTS_CHANGED_EVENT}. `revision` is the mutated
+ * DeviceSession revision for device-scoped reasons (`add`/`switch`/`signout`/
+ * `revoke`); for `login` (no device mutation at emit time) it is `0`. The
+ * payload is deliberately minimal and secret-free — the client refetches.
+ */
+export const sessionAccountsChangedEventSchema = z.object({
+    userId: z.string(),
+    revision: z.number().int().nonnegative(),
+    reason: sessionAccountsChangedReasonSchema,
+});

package/dist/esm/identity.js

@@ -187,9 +187,11 @@ export const domainVerificationInstructionsSchema = z.object({
     }),
 });
 export const authMethodEntrySchema = z.object({
-    type: z.enum(['identity', 'password', 'google', 'apple', 'github']),
+    type: z.enum(['identity', 'password', 'google', 'apple', 'github', 'webauthn']),
     linkedAt: z.union([z.string(), z.date()]),
     verificationMethodId: z.string().optional(),
+    credentialId: z.string().optional(),
+    name: z.string().optional(),
 });
 export const authMethodsResponseSchema = z.object({
     did: z.string(),

package/dist/esm/index.js

@@ -38,7 +38,21 @@ credentialRecordSchema, verifiableCredentialResponseSchema, credentialIssueResul
 export { 
 // Schemas
 linkPreviewSchema, linkPreviewBatchRequestSchema, linkPreviewBatchResponseSchema, linkPreviewResponseSchema, } from './links.js';
-export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, deviceHubTicketIssueRequestSchema, deviceHubTicketIssueResponseSchema, deviceHubTicketRedeemRequestSchema, deviceHubTicketRedeemResponseSchema, } from './deviceSession.js';
+export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, deviceHubTicketIssueRequestSchema, deviceHubTicketIssueResponseSchema, deviceHubTicketRedeemRequestSchema, deviceHubTicketRedeemResponseSchema, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedReasonSchema, sessionAccountsChangedEventSchema, } from './deviceSession.js';
 export { 
 // Schemas
 loginResultSchema, } from './deviceBoot.js';
+export { 
+// Shared primitives
+updatePlatformSchema, updateStatusSchema, updateAssetStatusSchema, sha256HexSchema, channelNameSchema, runtimeVersionSchema, rolloutPercentSchema, 
+// Assets: init + complete
+assetInitItemSchema, assetInitRequestSchema, assetUploadTicketSchema, assetInitResponseSchema, assetCompleteRequestSchema, assetCompleteResultItemSchema, assetCompleteResponseSchema, 
+// Create update
+updateAssetRefSchema, createUpdateRequestSchema, 
+// Read models
+updateSchema, createUpdateResponseSchema, rollbackToEmbeddedEntrySchema, channelSchema, channelListResponseSchema, updateListResponseSchema, 
+// Rollback / promote / rollout
+rollbackRequestSchema, rollbackToEmbeddedRequestSchema, promoteRequestSchema, updateRolloutPatchSchema, } from './updates.js';
+export { 
+// Schemas
+webauthnRegisterOptionsRequestSchema, webauthnLoginOptionsRequestSchema, webauthnRegisterVerifyRequestSchema, webauthnLoginVerifyRequestSchema, } from './webauthn.js';

package/dist/esm/updates.js

@@ -0,0 +1,247 @@
+/**
+ * Oxy Updates (self-hosted expo-updates protocol) — publish/admin API contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the AUTHENTICATED publish/admin
+ * surface that the `oxy-ship` CLI and the console Updates tab call. The PUBLIC
+ * manifest endpoint (`GET /updates/v1/apps/:clientId/manifest`) speaks the
+ * expo-updates v1 protocol verbatim (multipart/mixed, signed) and is therefore
+ * NOT modelled here — its shape is dictated by the Expo spec, not by us.
+ *
+ * The API validates its OUTPUT against these schemas; every consumer (the ship
+ * CLI, the console hook) validates its INPUT against the same definitions, so
+ * producer and consumers cannot drift.
+ *
+ * Domain model (mirrors the Mongoose models in `@oxyhq/api`):
+ *  - A `channel` (e.g. `production`, `preview`, `pr-123`) is a named release
+ *    track for one application.
+ *  - An `update` is one published bundle for a single `(channel, runtimeVersion,
+ *    platform)`. Its `updateId` is a UUIDv4 (the client parses it as a UUID).
+ *    The HEAD of a track is the newest `published` update for that tuple.
+ *  - An `asset` is content-addressed by its `sha256`; assets are shared across
+ *    updates and applications (an unchanged JS bundle is uploaded once).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/* -------------------------------------------------------------------------- */
+/*  Shared primitives                                                         */
+/* -------------------------------------------------------------------------- */
+/** The two platforms the expo-updates protocol addresses. */
+export const updatePlatformSchema = z.enum(['ios', 'android']);
+/** Lifecycle of a single published update row. */
+export const updateStatusSchema = z.enum(['published', 'superseded', 'rolled_back']);
+/** Upload lifecycle of a content-addressed asset. */
+export const updateAssetStatusSchema = z.enum(['pending', 'uploaded']);
+/** Lowercase-hex SHA-256 content hash (64 hex chars). */
+export const sha256HexSchema = z
+    .string()
+    .regex(/^[a-f0-9]{64}$/, 'sha256 must be 64 lowercase hex characters');
+/**
+ * A channel name. Constrained to a URL/path-safe slug so it can appear in the
+ * `expo-channel-name` header and be used CI-friendly for `pr-<n>` tracks. No
+ * colon (BullMQ/id safety) and no slash (path safety).
+ */
+export const channelNameSchema = z
+    .string()
+    .min(1)
+    .max(100)
+    .regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/, 'channel name must be a URL-safe slug');
+/** A runtime version string (expo-updates `runtimeVersion`, e.g. an appVersion). */
+export const runtimeVersionSchema = z.string().min(1).max(255);
+/** A rollout percentage: 0 rolls out to nobody, 100 to everybody. */
+export const rolloutPercentSchema = z.number().int().min(0).max(100);
+/* -------------------------------------------------------------------------- */
+/*  Assets: init + complete                                                   */
+/* -------------------------------------------------------------------------- */
+/**
+ * One asset the client intends to upload as part of an update. `sha256` is the
+ * content hash (dedup key); `contentType` and `size` describe the object the
+ * server will accept at the presigned URL.
+ */
+export const assetInitItemSchema = z.object({
+    sha256: sha256HexSchema,
+    contentType: z.string().min(1).max(255),
+    size: z.number().int().positive(),
+});
+/**
+ * `POST /updates/v1/assets/init` request. Declares the full asset set of an
+ * update; the server replies with a presigned PUT for every asset it does NOT
+ * already hold (content-addressed dedup — unchanged assets are never re-uploaded).
+ */
+export const assetInitRequestSchema = z.object({
+    applicationId: z.string().min(1),
+    assets: z.array(assetInitItemSchema).min(1).max(2000),
+});
+/** One presigned upload the client must PUT its bytes to before completing. */
+export const assetUploadTicketSchema = z.object({
+    sha256: sha256HexSchema,
+    /** Presigned S3 PUT URL. The client PUTs the exact bytes here. */
+    uploadUrl: z.string(),
+    /** The S3 key the object will live at (`public/updates/assets/<sha256>`). */
+    storageKey: z.string(),
+    /** The Content-Type the presigned URL was signed for; echo it on the PUT. */
+    contentType: z.string(),
+    /**
+     * The Cache-Control the presigned URL was signed for; the client MUST send it
+     * verbatim on the PUT so the SigV4 signature matches and the stored object
+     * carries the long immutable cache header (assets are content-addressed).
+     */
+    cacheControl: z.string(),
+});
+/**
+ * `POST /updates/v1/assets/init` response. `missing` holds a presigned upload
+ * for each asset the server does not yet have; `existing` lists the sha256s it
+ * already holds (the client skips those).
+ */
+export const assetInitResponseSchema = z.object({
+    missing: z.array(assetUploadTicketSchema),
+    existing: z.array(sha256HexSchema),
+});
+/**
+ * `POST /updates/v1/assets/complete` request. Sent after the client has PUT
+ * every `missing` asset. The server HEADs each object and flips it to
+ * `uploaded`; an object that is absent or size-mismatched is rejected.
+ */
+export const assetCompleteRequestSchema = z.object({
+    applicationId: z.string().min(1),
+    sha256s: z.array(sha256HexSchema).min(1).max(2000),
+});
+/** Per-asset verification outcome from `assets/complete`. */
+export const assetCompleteResultItemSchema = z.object({
+    sha256: sha256HexSchema,
+    status: updateAssetStatusSchema,
+    size: z.number().int().nonnegative(),
+});
+export const assetCompleteResponseSchema = z.object({
+    assets: z.array(assetCompleteResultItemSchema),
+});
+/* -------------------------------------------------------------------------- */
+/*  Create update                                                             */
+/* -------------------------------------------------------------------------- */
+/**
+ * A single asset reference inside a create-update request. `key` is the
+ * expo-export asset key (the md5-basename the client uses to look the asset up
+ * and skip embedded ones); `fileExtension` is the suggested on-disk extension.
+ */
+export const updateAssetRefSchema = z.object({
+    sha256: sha256HexSchema,
+    /** expo-export asset key (md5 basename) — how app code references the asset. */
+    key: z.string().min(1),
+    contentType: z.string().min(1),
+    /** Suggested file extension including the leading dot (e.g. `.js`, `.png`). */
+    fileExtension: z.string().optional(),
+});
+/**
+ * `POST /updates/v1/updates` request. Publishes one bundle for one platform to a
+ * channel (the channel is created on demand — CI-friendly for `pr-<n>`). All
+ * referenced assets MUST already be `uploaded` (via init/complete). `extra`
+ * MUST carry `expoClient` so `Constants.expoConfig` works after an OTA update.
+ */
+export const createUpdateRequestSchema = z.object({
+    applicationId: z.string().min(1),
+    channel: channelNameSchema,
+    runtimeVersion: runtimeVersionSchema,
+    platform: updatePlatformSchema,
+    /** The launch (entry-point) asset — its `fileExtension` is ignored by clients. */
+    launchAsset: updateAssetRefSchema,
+    assets: z.array(updateAssetRefSchema),
+    /**
+     * Opaque `extra` blob embedded verbatim in the signed manifest. MUST contain
+     * `expoClient` (the public expo config) so `Constants.expoConfig` resolves
+     * after an OTA update; MAY carry other third-party config.
+     */
+    extra: z
+        .object({ expoClient: z.record(z.string(), z.unknown()) })
+        .catchall(z.unknown()),
+    /** String→string metadata dict; filtered client-side via manifest filters. */
+    metadata: z.record(z.string(), z.string()).optional(),
+    /** Initial rollout percentage (default 100 — full rollout). */
+    rolloutPercent: rolloutPercentSchema.optional(),
+    /** Git commit the bundle was built from (audit / console display). */
+    gitCommit: z.string().max(100).optional(),
+    /** Git branch the bundle was built from (audit / console display). */
+    gitBranch: z.string().max(200).optional(),
+    /** Human-readable publish message (console display). */
+    message: z.string().max(500).optional(),
+});
+export const updateSchema = z.object({
+    id: z.string(),
+    applicationId: z.string(),
+    channel: z.string(),
+    runtimeVersion: z.string(),
+    platform: updatePlatformSchema,
+    status: updateStatusSchema,
+    rolloutPercent: rolloutPercentSchema,
+    launchAssetSha256: sha256HexSchema,
+    assetSha256s: z.array(sha256HexSchema),
+    gitCommit: z.string().optional(),
+    gitBranch: z.string().optional(),
+    message: z.string().optional(),
+    promotedFromUpdateId: z.string().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const createUpdateResponseSchema = z.object({
+    update: updateSchema,
+});
+export const rollbackToEmbeddedEntrySchema = z.object({
+    runtimeVersion: z.string(),
+    platform: updatePlatformSchema,
+    commitTime: z.string(),
+});
+export const channelSchema = z.object({
+    id: z.string(),
+    applicationId: z.string(),
+    name: z.string(),
+    rollbacksToEmbedded: z.array(rollbackToEmbeddedEntrySchema),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const channelListResponseSchema = z.object({
+    channels: z.array(channelSchema),
+});
+export const updateListResponseSchema = z.object({
+    updates: z.array(updateSchema),
+});
+/* -------------------------------------------------------------------------- */
+/*  Rollback / rollback-to-embedded / promote / rollout                       */
+/* -------------------------------------------------------------------------- */
+/**
+ * `POST /updates/v1/channels/:channel/rollback` request. Marks the current head
+ * for `(runtimeVersion, platform)` `rolled_back` so the previous published
+ * update (if any) becomes head again. Nothing is deleted.
+ */
+export const rollbackRequestSchema = z.object({
+    applicationId: z.string().min(1),
+    runtimeVersion: runtimeVersionSchema,
+    platform: updatePlatformSchema,
+});
+/**
+ * `POST /updates/v1/channels/:channel/rollback-to-embedded` request. Records a
+ * `rollBackToEmbedded` directive so clients on this `(runtimeVersion, platform)`
+ * fall back to the update embedded in their binary.
+ */
+export const rollbackToEmbeddedRequestSchema = z.object({
+    applicationId: z.string().min(1),
+    runtimeVersion: runtimeVersionSchema,
+    platform: updatePlatformSchema,
+});
+/**
+ * `POST /updates/v1/channels/:channel/promote` request. Promotes an existing
+ * update (by `updateId`) into the target channel by creating a NEW update (new
+ * UUID) pointing at the SAME assets. `toChannel` defaults to the path channel.
+ */
+export const promoteRequestSchema = z.object({
+    applicationId: z.string().min(1),
+    updateId: z.string().min(1),
+    /** Target channel to promote into. Defaults to the path `:channel`. */
+    toChannel: channelNameSchema.optional(),
+    /** Rollout percentage for the promoted update (default 100). */
+    rolloutPercent: rolloutPercentSchema.optional(),
+});
+/** `PATCH /updates/v1/updates/:updateId` request — adjust a rollout in place. */
+export const updateRolloutPatchSchema = z.object({
+    applicationId: z.string().min(1),
+    rolloutPercent: rolloutPercentSchema,
+});

package/dist/esm/webauthn.js

@@ -0,0 +1,60 @@
+/**
+ * WebAuthn / passkey ceremony contracts (Fase B/b1).
+ *
+ * These schemas describe ONLY the outer Oxy envelope that wraps a WebAuthn
+ * ceremony request — the username the client is registering/authenticating as,
+ * plus the device-session options every first-party sign-in accepts. The browser
+ * `RegistrationResponseJSON` / `AuthenticationResponseJSON` payloads are NOT
+ * mirrored here: they are validated by `@simplewebauthn/server` inside the route
+ * (`verifyRegistrationResponse` / `verifyAuthenticationResponse`), which is the
+ * single source of truth for their structure. Re-encoding them in Zod would just
+ * create a second, drift-prone definition of a shape we do not own.
+ */
+import { z } from 'zod';
+/**
+ * Device-session options shared by every first-party sign-in body
+ * (`deviceName`/`deviceFingerprint`/`deviceId`). Mirrors what
+ * `sessionCreateOptionsFromBody` reads in the API so a WebAuthn login/verify can
+ * name and pin its resulting session exactly like `/auth/login` or `/auth/verify`.
+ */
+const deviceSessionEnvelope = {
+    deviceName: z.string().trim().min(1).max(120).optional(),
+    deviceFingerprint: z.string().trim().min(1).max(256).optional(),
+    deviceId: z.string().trim().min(1).max(256).optional(),
+};
+/**
+ * `POST /webauthn/register/options` — request registration options. With a bearer
+ * token the caller links a passkey to their signed-in account and `username` is
+ * ignored; without one it is a prospective signup and `username` is the desired
+ * (not-yet-created) handle.
+ */
+export const webauthnRegisterOptionsRequestSchema = z.object({
+    username: z.string().trim().min(1).max(60).optional(),
+});
+/**
+ * `POST /webauthn/login/options` — request authentication options. When
+ * `username` is present the server scopes `allowCredentials` to that user's
+ * passkeys (username-first); when omitted it returns an empty allow-list for the
+ * usernameless / discoverable-credential flow (the default).
+ */
+export const webauthnLoginOptionsRequestSchema = z.object({
+    username: z.string().trim().min(1).max(60).optional(),
+});
+/**
+ * `POST /webauthn/register/verify` — the outer envelope. The browser
+ * `RegistrationResponseJSON` travels alongside these fields under `response` and
+ * is validated by `@simplewebauthn/server`, not here. `username` is required only
+ * for the prospective-signup branch (no bearer); the linking branch ignores it.
+ */
+export const webauthnRegisterVerifyRequestSchema = z.object({
+    username: z.string().trim().min(1).max(60).optional(),
+    ...deviceSessionEnvelope,
+});
+/**
+ * `POST /webauthn/login/verify` — the outer envelope. The browser
+ * `AuthenticationResponseJSON` travels alongside these fields under `response`
+ * and is validated by `@simplewebauthn/server`, not here.
+ */
+export const webauthnLoginVerifyRequestSchema = z.object({
+    ...deviceSessionEnvelope,
+});