@oxyhq/contracts 0.18.0 → 0.20.0

package/dist/types/commonsSignIn.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Canonical contract for the "Sign in with Oxy" approval handoff.
+ *
+ * SINGLE SOURCE OF TRUTH for the closed set of reasons an approver may attach
+ * when it DENIES a pending request via
+ * `POST /auth/session/deny/:authorizeCode`.
+ *
+ * That endpoint is UNAUTHENTICATED — the public `authorizeCode` is the only
+ * credential — so a free-form string from it is never stored: it would be an
+ * unauthenticated write of arbitrary text onto a record other surfaces read.
+ * The set is therefore deliberately tiny, and closed:
+ *
+ *  - `'declined'` the approver rejected a request they recognised ("Not now").
+ *  - `'not_me'`   the approver did not start the request ("This wasn't me").
+ *                 The ONE value that records the denial as suspicious rather
+ *                 than an ordinary cancel, so a UI may only offer it where the
+ *                 user genuinely said so.
+ *
+ * Why this lives in `@oxyhq/contracts` rather than in either consumer: the same
+ * closed set is enforced in three places — the request schema of the API route,
+ * the `enum` of the persisted `AuthSession.deniedReason` field, and the client
+ * SDK's `denyCommonsSignIn` parameter. Two hand-maintained copies of a wire
+ * contract drift the moment a value is added on one side only, and the failure
+ * lands at runtime, in an auth path, as a generic validation error. One
+ * declaration makes that impossible.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/**
+ * The closed set, as a value — consumed directly where a runtime list is
+ * required (e.g. the Mongoose `enum` of `AuthSession.deniedReason`, which is
+ * the storage-level guarantee that an unauthenticated caller can never write
+ * free-form text into the field).
+ */
+export declare const COMMONS_DENY_REASONS: readonly ["declined", "not_me"];
+/**
+ * The same set as a zod enum — the edge validator. Anything outside it
+ * (including free-form text) is rejected with 400 before any handler runs.
+ */
+export declare const commonsDenyReasonSchema: z.ZodEnum<["declined", "not_me"]>;
+/** Why the approver denied a "Sign in with Oxy" request. */
+export type CommonsDenyReason = z.infer<typeof commonsDenyReasonSchema>;
+/**
+ * Android notification channel id the identity-approval push is sent on.
+ *
+ * A wire contract for the same reason the deny set is: Android 8+ DROPS a
+ * notification whose channel id the app has not created, silently and with no
+ * client-side error. The API attaches this id when it sends, and the vault
+ * creates the channel with it before registering a push token — two hand-typed
+ * copies of that string would fail as "the notification never arrived", which
+ * is the single hardest push symptom to diagnose.
+ *
+ * The channel's user-visible NAME and description are deliberately NOT here:
+ * those are localized app copy, and the vault owns them.
+ */
+export declare const IDENTITY_APPROVAL_PUSH_CHANNEL = "auth-approval";

package/dist/types/deviceSession.d.ts

@@ -281,51 +281,6 @@ export declare const deviceTokenMintResponseSchema: z.ZodObject<{
 }>;
 export type DeviceTokenMintRequest = z.infer<typeof deviceTokenMintRequestSchema>;
 export type DeviceTokenMintResponse = z.infer<typeof deviceTokenMintResponseSchema>;
-/** Request body for `POST /session/device/hub-ticket`. */
-export declare const deviceHubTicketIssueRequestSchema: z.ZodObject<{
-    returnOrigin: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    returnOrigin: string;
-}, {
-    returnOrigin: string;
-}>;
-/** Response from `POST /session/device/hub-ticket`. */
-export declare const deviceHubTicketIssueResponseSchema: z.ZodObject<{
-    ticket: z.ZodString;
-    expiresIn: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    ticket: string;
-    expiresIn: number;
-}, {
-    ticket: string;
-    expiresIn: number;
-}>;
-/** Request body for `POST /session/device/redeem-ticket`. */
-export declare const deviceHubTicketRedeemRequestSchema: z.ZodObject<{
-    ticket: z.ZodString;
-    returnOrigin: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    returnOrigin: string;
-    ticket: string;
-}, {
-    returnOrigin: string;
-    ticket: string;
-}>;
-/** Response from `POST /session/device/redeem-ticket`. */
-export declare const deviceHubTicketRedeemResponseSchema: z.ZodObject<{
-    deviceId: z.ZodString;
-    deviceSecret: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    deviceId: string;
-    deviceSecret: string;
-}, {
-    deviceId: string;
-    deviceSecret: string;
-}>;
-export type DeviceHubTicketIssueRequest = z.infer<typeof deviceHubTicketIssueRequestSchema>;
-export type DeviceHubTicketIssueResponse = z.infer<typeof deviceHubTicketIssueResponseSchema>;
-export type DeviceHubTicketRedeemRequest = z.infer<typeof deviceHubTicketRedeemRequestSchema>;
-export type DeviceHubTicketRedeemResponse = z.infer<typeof deviceHubTicketRedeemResponseSchema>;
 /**
  * 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.
@@ -368,3 +323,88 @@ export declare const sessionAccountsChangedEventSchema: z.ZodObject<{
 }>;
 export type SessionAccountsChangedReason = z.infer<typeof sessionAccountsChangedReasonSchema>;
 export type SessionAccountsChangedEvent = z.infer<typeof sessionAccountsChangedEventSchema>;
+/**
+ * Response from `POST /session/device/background-credential` — provisioned by
+ * the SDK WHILE THE APP IS RUNNING (bearer required, `deviceId` and account
+ * 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.
+ *
+ * The raw `secret` is returned exactly once, at provision time — never stored
+ * retrievably, never logged, never re-read. A caller that loses it provisions
+ * a new one.
+ *
+ * `expiresAt` is an unvalidated string, like every other expiry in this file:
+ * no consumer on the JS path interprets it (native background code parses it
+ * itself), and a `.datetime()` here alone would leave one strict field beside
+ * two lax ones. If expiry is ever validated it goes on all three at once, with
+ * the API's serializers checked against it — the producer is the same server.
+ */
+export declare const deviceBackgroundCredentialResponseSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    secret: z.ZodString;
+    accountId: z.ZodString;
+    expiresAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    expiresAt: string;
+    deviceId: string;
+    accountId: string;
+    secret: string;
+}, {
+    expiresAt: string;
+    deviceId: string;
+    accountId: string;
+    secret: string;
+}>;
+/**
+ * Request body for `POST /session/device/background-token` — presented by
+ * 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.
+ */
+export declare const deviceBackgroundTokenRequestSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    secret: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    deviceId: string;
+    secret: string;
+}, {
+    deviceId: string;
+    secret: string;
+}>;
+/**
+ * Wire shape of a successful `POST /session/device/background-token`: the short
+ * access token, its expiry, and the account the token belongs to — the last so
+ * a caller can key cached data per account and drop data belonging to a
+ * foreign one.
+ *
+ * Carries NO device state — no account list, no `activeAccountId`, no
+ * `revision`, unlike {@link deviceTokenMintResponseSchema} — deliberately, to
+ * cap what a compromised credential record yields.
+ */
+export declare const deviceBackgroundTokenResponseSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    expiresAt: z.ZodString;
+    accountId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    expiresAt: string;
+    accessToken: string;
+    accountId: string;
+}, {
+    expiresAt: string;
+    accessToken: string;
+    accountId: string;
+}>;
+export type DeviceBackgroundCredentialResponse = z.infer<typeof deviceBackgroundCredentialResponseSchema>;
+export type DeviceBackgroundTokenRequest = z.infer<typeof deviceBackgroundTokenRequestSchema>;
+export type DeviceBackgroundTokenResponse = z.infer<typeof deviceBackgroundTokenResponseSchema>;

package/dist/types/inboxPush.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Canonical contract for Inbox new-mail push notifications.
+ *
+ * The Android channel id and payload `type` are wire contracts: Android 8+
+ * drops a notification whose channel the app has not created, and the client
+ * only routes taps it recognises. Two hand-typed copies of either string fail as
+ * "the notification never arrived" or "tapping does nothing" — the hardest push
+ * symptoms to diagnose.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo.
+ */
+import { z } from 'zod';
+/** Android notification channel id the new-mail push is sent on. */
+export declare const INBOX_EMAIL_PUSH_CHANNEL = "email";
+/** Runtime type discriminator of the new-mail push payload. */
+export declare const INBOX_EMAIL_PUSH_TYPE = "oxy_inbox_new_message";
+export declare const inboxEmailPushDataSchema: z.ZodObject<{
+    type: z.ZodLiteral<"oxy_inbox_new_message">;
+    messageId: z.ZodString;
+    mailboxId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "oxy_inbox_new_message";
+    messageId: string;
+    mailboxId: string;
+}, {
+    type: "oxy_inbox_new_message";
+    messageId: string;
+    mailboxId: string;
+}>;
+export type InboxEmailPushData = z.infer<typeof inboxEmailPushDataSchema>;

package/dist/types/index.d.ts

@@ -15,6 +15,10 @@ export { userNameSchema, userRelationshipSchema, themePreferenceSchema, userResp
 export type { UserNameResponse, UserRelationship, ThemePreference, UserResponse, UserProfileUpdate, CurrentUserResponseContract, DeviceLinkedSessionResponse, DeviceLinkedSessionsResponseContract, } from './userResponse';
 export { applicationTypeSchema, publicApplicationSchema, sessionStatusSchema, } from './sessionStatus';
 export type { ApplicationTypeContract, PublicApplicationResponse, SessionStatusResponse, } from './sessionStatus';
+export { COMMONS_DENY_REASONS, commonsDenyReasonSchema, IDENTITY_APPROVAL_PUSH_CHANNEL, } from './commonsSignIn';
+export type { CommonsDenyReason } from './commonsSignIn';
+export { INBOX_EMAIL_PUSH_CHANNEL, INBOX_EMAIL_PUSH_TYPE, inboxEmailPushDataSchema, } from './inboxPush';
+export type { InboxEmailPushData } from './inboxPush';
 export { recommendationExcludeTypeSchema, recommendationBoostSchema, recommendationSignalWeightsSchema, recommendationRequestSchema, recommendationCountSchema, recommendationItemSchema, recommendationResponseSchema, appEndorsementInputSchema, appInterestInputSchema, appUserSignalIngestSchema, appAffinityEventTypeSchema, appAffinityEventSchema, appAffinityEventsIngestSchema, } from './recommendations';
 export type { RecommendationExcludeType, RecommendationBoost, RecommendationSignalWeights, RecommendationRequest, RecommendationCount, RecommendationItem, RecommendationResponse, AppEndorsementInput, AppInterestInput, AppUserSignalIngest, AppAffinityEventType, AppAffinityEvent, AppAffinityEventsIngest, } from './recommendations';
 export { verificationMethodSchema, didServiceSchema, didDocumentSchema, signedRecordEnvelopeSchema, verifiedDomainSchema, domainVerificationRequestSchema, domainVerificationInstructionsSchema, authMethodEntrySchema, authMethodsResponseSchema, exportAttestationSchema, exportBundleSchema, } from './identity';
@@ -25,10 +29,12 @@ export { chainHeadResponseSchema, logPageResponseSchema, } from './protocol';
 export type { LexiconRecord, ChainHeadResponse, LogPageResponse, } from './protocol';
 export { publicCardSchema, signedPublicCardSchema, realLifeAttestationRecordSchema, realLifeAttestationResultSchema, validationVerdictRecordSchema, validationOpenRequestSchema, validationOpenResultSchema, validationRequestSummarySchema, validationVoteResultSchema, personhoodVouchRecordSchema, personhoodBreakdownSchema, personhoodStatusResultSchema, vouchResultSchema, credentialRecordSchema, verifiableCredentialResponseSchema, credentialIssueResultSchema, credentialListResultSchema, credentialVerifyResultSchema, } from './civic';
 export type { CardTrustTier, PersonhoodStatus, PublicCard, SignedPublicCard, RealLifeAttestationRecord, RealLifeAttestationResult, ValidationVerdict, ValidationRequestStatus, ValidationVerdictRecord, ValidationOpenRequest, ValidationOpenResult, ValidationRequestSummary, ValidationVoteResult, PersonhoodVouchRecord, PersonhoodBreakdown, PersonhoodStatusResult, VouchResult, CredentialStatus, CredentialRecord, VerifiableCredentialResponse, CredentialIssueResult, CredentialListResult, CredentialVerifyResult, } from './civic';
+export { REPUTATION_CATEGORIES, REPUTATION_TRANSACTION_STATUSES, TRUST_TIERS, REPUTATION_TARGET_ENTITY_TYPES, REPUTATION_DISPUTE_STATUSES, REPUTATION_INFLUENCE_CONTEXTS, reputationCategorySchema, reputationTransactionStatusSchema, trustTierSchema, reputationTargetEntityTypeSchema, reputationDisputeStatusSchema, reputationInfluenceContextSchema, reputationTransactionSchema, reputationBalanceBreakdownSchema, reputationInfluenceSchema, reputationReliabilitySchema, reputationBalanceSummarySchema, reputationBalanceSchema, reputationDisputeSchema, reputationRuleSchema, reputationLeaderboardUserSchema, reputationLeaderboardEntrySchema, reputationInfluenceResultSchema, reverseReputationTransactionResultSchema, awardReputationSchema, createReputationDisputeSchema, resolveReputationDisputeSchema, upsertReputationRuleSchema, reverseReputationTransactionSchema, isFullReputationBalance, } from './reputation';
+export type { ReputationCategory, ReputationTransactionStatus, TrustTier, ReputationTargetEntityType, ReputationDisputeStatus, ReputationInfluenceContext, ReputationTransaction, ReputationBalanceBreakdown, ReputationInfluence, ReputationReliability, ReputationBalanceSummary, ReputationBalance, ReputationBalanceView, ReputationDispute, ReputationRule, ReputationLeaderboardUser, ReputationLeaderboardEntry, ReputationInfluenceResult, ReverseReputationTransactionResult, AwardReputationInput, CreateReputationDisputeInput, ResolveReputationDisputeInput, UpsertReputationRuleInput, UpsertReputationRuleRequest, ReverseReputationTransactionInput, } from './reputation';
 export { linkPreviewSchema, linkPreviewBatchRequestSchema, linkPreviewBatchResponseSchema, linkPreviewResponseSchema, } from './links';
 export type { LinkPreviewStatus, LinkPreview, LinkPreviewBatchRequest, LinkPreviewBatchResponse, } from './links';
-export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, deviceHubTicketIssueRequestSchema, deviceHubTicketIssueResponseSchema, deviceHubTicketRedeemRequestSchema, deviceHubTicketRedeemResponseSchema, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedReasonSchema, sessionAccountsChangedEventSchema, } from './deviceSession';
-export type { SessionAccount, DeviceSessionState, ActiveToken, DeviceSessionSync, DeviceTokenMintRequest, DeviceTokenMintResponse, DeviceHubTicketIssueRequest, DeviceHubTicketIssueResponse, DeviceHubTicketRedeemRequest, DeviceHubTicketRedeemResponse, SessionAccountsChangedReason, SessionAccountsChangedEvent, } from './deviceSession';
+export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, deviceBackgroundCredentialResponseSchema, deviceBackgroundTokenRequestSchema, deviceBackgroundTokenResponseSchema, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedReasonSchema, sessionAccountsChangedEventSchema, } from './deviceSession';
+export type { SessionAccount, DeviceSessionState, ActiveToken, DeviceSessionSync, DeviceTokenMintRequest, DeviceTokenMintResponse, DeviceBackgroundCredentialResponse, DeviceBackgroundTokenRequest, DeviceBackgroundTokenResponse, SessionAccountsChangedReason, SessionAccountsChangedEvent, } from './deviceSession';
 export { loginResultSchema, } from './deviceBoot';
 export type { LoginSessionResult, LoginResult, SecurityAlert, SecurityAlertAnomaly, } from './deviceBoot';
 export { rotateKeyChallengeResponseSchema, rotateKeyCompleteRequestSchema, rotateKeyCompleteResponseSchema, } from './keyRotation';

package/dist/types/keyRecovery.d.ts

@@ -62,18 +62,18 @@ export declare const encryptedBackupEnvelopeSchema: z.ZodObject<{
     version: number;
     nonce: string;
     ciphertext: string;
+    createdAt: string;
     algorithm: "xchacha20poly1305";
     kdfInfo: string;
     publicKeyHint: string;
-    createdAt: string;
 }, {
     version: number;
     nonce: string;
     ciphertext: string;
+    createdAt: string;
     algorithm: "xchacha20poly1305";
     kdfInfo: string;
     publicKeyHint: string;
-    createdAt: string;
 }>;
 export type EncryptedBackupEnvelope = z.infer<typeof encryptedBackupEnvelopeSchema>;
 /**
@@ -101,19 +101,19 @@ export declare const backupUploadRequestSchema: z.ZodObject<{
     version: number;
     nonce: string;
     ciphertext: string;
+    createdAt: string;
     algorithm: "xchacha20poly1305";
     kdfInfo: string;
     publicKeyHint: string;
-    createdAt: string;
     lookupId: string;
 }, {
     version: number;
     nonce: string;
     ciphertext: string;
+    createdAt: string;
     algorithm: "xchacha20poly1305";
     kdfInfo: string;
     publicKeyHint: string;
-    createdAt: string;
     lookupId: string;
 }>;
 export type BackupUploadRequest = z.infer<typeof backupUploadRequestSchema>;
@@ -128,11 +128,11 @@ export declare const backupStatusResponseSchema: z.ZodObject<{
     createdAt: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     exists: boolean;
-    publicKeyHint?: string | undefined;
     createdAt?: string | undefined;
+    publicKeyHint?: string | undefined;
 }, {
     exists: boolean;
-    publicKeyHint?: string | undefined;
     createdAt?: string | undefined;
+    publicKeyHint?: string | undefined;
 }>;
 export type BackupStatusResponse = z.infer<typeof backupStatusResponseSchema>;