@oxy.so/contracts 2.2.0 → 4.0.0

package/dist/types/accountEmail.d.ts

@@ -1,22 +1,26 @@
 /**
- * Recovery email contracts (ADR 0029 D3).
+ * Email codes and tickets (ADR 0030).
  *
- * A web account is a username, a passkey and a recovery email. The email is
- * proven by a 6-digit code sent to it, and the proof is a short-lived one-use
- * ticket the next step spends:
+ * A web account is a username and an email; a password and an authenticator
+ * app are optional and added later. The email is proven by a 6-digit code sent
+ * to it, and the proof is a short-lived one-use ticket the next step spends:
  *
- * - `signup`: the ticket lets `POST /webauthn/register/verify` create the
- *   account with that email;
- * - `recovery`: the person names their username or email, the code goes to the
- *   account's recovery email, and the ticket lets them register a new passkey
- *   for that account.
+ * - `signup`: the ticket lets `POST /auth/signup` create the account with that
+ *   email. `start` answers the same whether or not the address already has an
+ *   account, so it never tells anyone which emails have an Oxy account.
  *
- * `start` answers the same whether or not an account exists, so neither purpose
- * tells anyone which emails or usernames have an Oxy account. An account with a
- * Commons key has no recovery email: it recovers in Commons.
+ * Signing in by email (`signin`) and re-verifying before a sensitive change
+ * (`reauth`) use the same code, through their own routes (`signIn.ts`).
  */
 import { z } from 'zod';
-export declare const EMAIL_VERIFICATION_PURPOSES: readonly ["signup", "recovery"];
+/**
+ * - `signup`: above.
+ * - `signin`: the code (and link) of an email sign-in (`POST /auth/signin/email/start`).
+ * - `reauth`: a signed-in person proving it is them before a sensitive step
+ *   (`POST /users/me/reauth/email`): a password, an authenticator, deleting the
+ *   account, linking Commons.
+ */
+export declare const EMAIL_VERIFICATION_PURPOSES: readonly ["signup", "signin", "reauth"];
 export type EmailVerificationPurpose = (typeof EMAIL_VERIFICATION_PURPOSES)[number];
 /** Digits in a code. */
 export declare const EMAIL_CODE_LENGTH = 6;
@@ -31,7 +35,7 @@ export declare const emailAddressSchema: z.ZodString;
 /** An opaque one-use ticket (32 random bytes, base64url). */
 export declare const emailTicketSchema: z.ZodString;
 /** `POST /auth/email/verify/start` */
-export declare const emailVerificationStartRequestSchema: z.ZodDiscriminatedUnion<"purpose", [z.ZodObject<{
+export declare const emailVerificationStartRequestSchema: z.ZodObject<{
     purpose: z.ZodLiteral<"signup">;
     email: z.ZodString;
 }, "strict", z.ZodTypeAny, {
@@ -40,17 +44,7 @@ export declare const emailVerificationStartRequestSchema: z.ZodDiscriminatedUnio
 }, {
     purpose: "signup";
     email: string;
-}>, z.ZodObject<{
-    purpose: z.ZodLiteral<"recovery">;
-    /** The account's username, or its recovery email. */
-    identifier: z.ZodString;
-}, "strict", z.ZodTypeAny, {
-    purpose: "recovery";
-    identifier: string;
-}, {
-    purpose: "recovery";
-    identifier: string;
-}>]>;
+}>;
 export type EmailVerificationStartRequest = z.infer<typeof emailVerificationStartRequestSchema>;
 export interface EmailVerificationStartResponse {
     /** Names this verification in `confirm`. Returned whether or not a code was sent. */
@@ -75,8 +69,6 @@ export interface EmailVerificationConfirmResponse {
     ticket: string;
     /** Unix milliseconds after which the ticket is refused. */
     expiresAt: number;
-    /** Recovery only: the account the ticket recovers. `null` for sign-up. */
-    username: string | null;
 }
 export declare const emailVerificationConfirmResponseSchema: z.ZodType<EmailVerificationConfirmResponse>;
 /**
@@ -90,7 +82,7 @@ export declare const EMAIL_VERIFICATION_ERROR_CODES: {
     readonly tooManyAttempts: "EMAIL_CODE_TOO_MANY_ATTEMPTS";
     /** The ticket is unknown, expired, spent, or for another email or purpose. */
     readonly ticketInvalid: "EMAIL_TICKET_INVALID";
-    /** A sign-up without a confirmed recovery email. */
+    /** A sign-up without a confirmed email. */
     readonly ticketRequired: "EMAIL_TICKET_REQUIRED";
     /** This server cannot send mail. */
     readonly unavailable: "EMAIL_UNAVAILABLE";

package/dist/types/accountGraph.d.ts

@@ -315,8 +315,8 @@ export declare const createAccountRequestSchema: z.ZodEffects<z.ZodObject<{
      */
     isPrivateAccount: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
-    username: string;
     kind: "bot" | "organization" | "project" | "channel";
+    username: string;
     parentAccountId?: string | undefined;
     name?: {
         first?: string | undefined;
@@ -330,8 +330,8 @@ export declare const createAccountRequestSchema: z.ZodEffects<z.ZodObject<{
     accountCategories?: ("security" | "news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[] | undefined;
     isPrivateAccount?: boolean | undefined;
 }, {
-    username: string;
     kind: "bot" | "organization" | "project" | "channel";
+    username: string;
     parentAccountId?: string | undefined;
     name?: {
         first?: string | undefined;
@@ -345,8 +345,8 @@ export declare const createAccountRequestSchema: z.ZodEffects<z.ZodObject<{
     accountCategories?: ("security" | "news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[] | undefined;
     isPrivateAccount?: boolean | undefined;
 }>, {
-    username: string;
     kind: "bot" | "organization" | "project" | "channel";
+    username: string;
     parentAccountId?: string | undefined;
     name?: {
         first?: string | undefined;
@@ -360,8 +360,8 @@ export declare const createAccountRequestSchema: z.ZodEffects<z.ZodObject<{
     accountCategories?: ("security" | "news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[] | undefined;
     isPrivateAccount?: boolean | undefined;
 }, {
-    username: string;
     kind: "bot" | "organization" | "project" | "channel";
+    username: string;
     parentAccountId?: string | undefined;
     name?: {
         first?: string | undefined;

package/dist/types/deviceBoot.d.ts

@@ -4,8 +4,8 @@
  * SINGLE SOURCE OF TRUTH for the first-party login result (the session arm). The
  * API validates its OUTPUT against this schema; every consumer (`@oxy.so/core`'s
  * auth mixin) validates its INPUT against the same definition, so producer and
- * consumers cannot drift. Sign-in is passkey (WebAuthn) or Commons handoff —
- * password and 2FA were removed, so the only outcome is a completed session.
+ * consumers cannot drift. This is the session arm every sign-in
+ * ends in (email code or link, password, authenticator, Commons handoff).
  *
  * The device transport is `deviceId` + `deviceSecret` + `POST /session/device/token`
  * (see `deviceSession.ts`). The legacy cookie/bootstrap/refresh-family lanes were

package/dist/types/deviceSession.d.ts

@@ -166,9 +166,10 @@ export type DeviceSessionSync = z.infer<typeof deviceSessionSyncSchema>;
 /**
  * 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.
+ * possession of the secret IS the proof of device ownership. The server looks
+ * `sha256(deviceSecret)` up among the device's holder credentials (one per app
+ * or origin that joined the shared DeviceSession) and mints a short access
+ * token for the device's active account.
  *
  * `accountId` pins the mint to ONE account of that device instead of whichever
  * account is currently active. It exists for identity-bound clients (Commons),
@@ -196,8 +197,8 @@ export declare const deviceTokenMintRequestSchema: z.ZodObject<{
  * short access token for the active account, its expiry, the device secret the
  * client must persist (`nextDeviceSecret` — on mint this echoes the presented
  * secret unchanged so concurrent refreshes from multiple origins do not race),
- * and the projected device-session state. Sign-in rotates the secret via
- * `issueDeviceSecret`; mint does not.
+ * and the projected device-session state. Nothing rotates: each sign-in issues
+ * a NEW holder credential and leaves the others valid.
  */
 export declare const deviceTokenMintResponseSchema: z.ZodObject<{
     accessToken: z.ZodString;
@@ -330,12 +331,11 @@ export type SessionAccountsChangedEvent = z.infer<typeof sessionAccountsChangedE
  * derived server-side from it) and consumed afterwards only by native
  * background code, which has no JS runtime to mint a token for itself.
  *
- * Deliberately a SEPARATE credential from the rotating `deviceSecret`: that one
- * rotates on every mint, so background code presenting it would become a second
- * writer of a value the JS runtime depends on, and background code killed
- * mid-rotation would silently sign the user out on the next cold start. Against
- * this credential background code is the sole writer, and it can never rotate
- * anything JS reads.
+ * Deliberately a SEPARATE credential from the holder `deviceSecret`: that one
+ * is device-wide and mints for whichever account is active, while this one is
+ * bound to ONE account and expires, so a widget worker never holds a
+ * credential that reaches every account on the device. Background code is its
+ * sole writer and never touches anything JS reads.
  *
  * The raw `secret` is returned exactly once, at provision time — never stored
  * retrievably, never logged, never re-read. A caller that loses it provisions
@@ -368,10 +368,10 @@ export declare const deviceBackgroundCredentialResponseSchema: z.ZodObject<{
  * native background code with NO bearer and NO cookies: possession of the
  * background `secret` IS the proof, as it is for the device-secret mint.
  *
- * Unlike that mint this one NEVER rotates the presented secret (hence no
- * `next…` field to persist in the response), so background code interrupted
- * anywhere between request and response leaves the credential intact and
- * usable on its next run.
+ * Like that mint this one NEVER rotates the presented secret, and it carries
+ * no `next…` field at all, so background code interrupted anywhere between
+ * request and response leaves the credential intact and usable on its next
+ * run.
  */
 export declare const deviceBackgroundTokenRequestSchema: z.ZodObject<{
     deviceId: z.ZodString;
@@ -409,3 +409,115 @@ export declare const deviceBackgroundTokenResponseSchema: z.ZodObject<{
 export type DeviceBackgroundCredentialResponse = z.infer<typeof deviceBackgroundCredentialResponseSchema>;
 export type DeviceBackgroundTokenRequest = z.infer<typeof deviceBackgroundTokenRequestSchema>;
 export type DeviceBackgroundTokenResponse = z.infer<typeof deviceBackgroundTokenResponseSchema>;
+/**
+ * Proof that the caller holds a device: the `deviceId` it stored first-party and
+ * one of that device's holder secrets. Sent with `POST /session/device/join-code`
+ * and, optionally, with a sign-in (`POST /auth/session/claim`, the email,
+ * password and second-factor sign-ins, `POST /auth/signup`), where
+ * a valid proof puts the new session on THAT device so every app holding it sees
+ * the account. An invalid proof on a sign-in is ignored, never an error.
+ */
+export declare const deviceProofSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    deviceSecret: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    deviceId: string;
+    deviceSecret: string;
+}, {
+    deviceId: string;
+    deviceSecret: string;
+}>;
+/**
+ * `POST /session/device/register` — auth.oxy.so only. No body. A new, empty
+ * DeviceSession with a server-chosen `deviceId` and ONE holder credential for
+ * auth.oxy.so. The raw secret is returned exactly once.
+ */
+export declare const deviceRegisterResponseSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    deviceSecret: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    deviceId: string;
+    deviceSecret: string;
+}, {
+    deviceId: string;
+    deviceSecret: string;
+}>;
+/**
+ * `POST /session/device/join-code` — auth.oxy.so only (the bridge window). Proves
+ * auth.oxy.so's device and asks for a one-use code an official app redeems to
+ * join it. The code is bound to the application (`clientId`), its exact
+ * registered `redirectUri` and the app's PKCE challenge, and lives about a
+ * minute.
+ */
+export declare const deviceJoinCodeRequestSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    deviceSecret: z.ZodString;
+} & {
+    clientId: z.ZodString;
+    redirectUri: z.ZodString;
+    codeChallenge: z.ZodString;
+    codeChallengeMethod: z.ZodLiteral<"S256">;
+}, "strip", z.ZodTypeAny, {
+    deviceId: string;
+    deviceSecret: string;
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+}, {
+    deviceId: string;
+    deviceSecret: string;
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+}>;
+export declare const deviceJoinCodeResponseSchema: z.ZodObject<{
+    code: z.ZodString;
+    /** Seconds until the code expires. */
+    expiresIn: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    expiresIn: number;
+}, {
+    code: string;
+    expiresIn: number;
+}>;
+/**
+ * `POST /session/device/join` — called by the app's own origin with the code the
+ * bridge window posted to it and the PKCE verifier only the app holds. Returns a
+ * NEW holder credential for the browser's device; the app then mints through the
+ * ordinary `POST /session/device/token`.
+ */
+export declare const deviceJoinRequestSchema: z.ZodObject<{
+    code: z.ZodString;
+    codeVerifier: z.ZodString;
+    clientId: z.ZodString;
+    redirectUri: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    clientId: string;
+    redirectUri: string;
+    codeVerifier: string;
+}, {
+    code: string;
+    clientId: string;
+    redirectUri: string;
+    codeVerifier: string;
+}>;
+export declare const deviceJoinResponseSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    deviceSecret: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    deviceId: string;
+    deviceSecret: string;
+}, {
+    deviceId: string;
+    deviceSecret: string;
+}>;
+export type DeviceProof = z.infer<typeof deviceProofSchema>;
+export type DeviceRegisterResponse = z.infer<typeof deviceRegisterResponseSchema>;
+export type DeviceJoinCodeRequest = z.infer<typeof deviceJoinCodeRequestSchema>;
+export type DeviceJoinCodeResponse = z.infer<typeof deviceJoinCodeResponseSchema>;
+export type DeviceJoinRequest = z.infer<typeof deviceJoinRequestSchema>;
+export type DeviceJoinResponse = z.infer<typeof deviceJoinResponseSchema>;