@oxy.so/contracts 6.12.0 → 6.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,129 @@
1
+ /**
2
+ * A platform that holds the Oxy session (ADR 0058).
3
+ *
4
+ * OxyOS (`oxyos-accountd`) and Astro hold the person's Oxy session on a
5
+ * PLATFORM CREDENTIAL: a device holder credential issued to the platform's own
6
+ * sign-in, the one that names it with {@link platformClientSchema}
7
+ * (`POST /auth/signin/password`, completed by `POST /auth/signin/second-factor`).
8
+ * Applications they run hold nothing; the platform asks
9
+ * `POST /session/device/app-token` for a five-minute token named for each one
10
+ * (`azp`, and the `host` claim naming the platform and its credential).
11
+ *
12
+ * The Zod-free half (vocabularies, the response check) is
13
+ * `./client/platformSession.ts`.
14
+ */
15
+ import { z } from 'zod';
16
+ import { APP_TOKEN_DEVICE_ACCESS_DENIED, DEVICE_APP_TOKEN_ERROR_CODES, DEVICE_APP_TOKEN_TTL_SECONDS, OXYOS_DESKTOP_ENTRY_ID_PATTERN, PLATFORM_HOSTS } from './client/platformSession';
17
+ export { APP_TOKEN_DEVICE_ACCESS_DENIED, DEVICE_APP_TOKEN_ERROR_CODES, DEVICE_APP_TOKEN_TTL_SECONDS, OXYOS_DESKTOP_ENTRY_ID_PATTERN, PLATFORM_HOSTS, };
18
+ /**
19
+ * Names the platform on its own password sign-in, and on the second factor
20
+ * completing it. Honoured only when the request has NO web `Origin` and
21
+ * `clientId` is a live public client id of an active Oxy application whose
22
+ * registry entry declares `platformHost` equal to `platform`; anything else is
23
+ * refused with the ordinary invalid-request answer before any account lookup or
24
+ * password work. When honoured, the device credential the sign-in returns is a
25
+ * platform credential, and a credential the sign-in's `device` proof presented
26
+ * is retired.
27
+ */
28
+ export declare const platformClientSchema: z.ZodObject<{
29
+ platform: z.ZodEnum<{
30
+ oxyos: "oxyos";
31
+ astro: "astro";
32
+ }>;
33
+ clientId: z.ZodString;
34
+ }, z.core.$strict>;
35
+ /**
36
+ * Which application the token is for, as the platform vouches for it:
37
+ *
38
+ * - `{ platform: 'oxyos', desktopEntryId }`: an application OxyOS launched,
39
+ * by the desktop entry id its registry entry declares;
40
+ * - `{ platform, self: true }`: the platform's own application (OxyOS's
41
+ * Settings and shell, Astro's chrome);
42
+ * - `{ platform: 'astro', origin, clientId }`: an Oxy web application Astro
43
+ * shows, by the exact origin it committed and the application's client id.
44
+ */
45
+ export declare const deviceAppTokenAttestationSchema: z.ZodUnion<readonly [z.ZodObject<{
46
+ platform: z.ZodLiteral<"oxyos">;
47
+ desktopEntryId: z.ZodString;
48
+ }, z.core.$strict>, z.ZodObject<{
49
+ platform: z.ZodEnum<{
50
+ oxyos: "oxyos";
51
+ astro: "astro";
52
+ }>;
53
+ self: z.ZodLiteral<true>;
54
+ }, z.core.$strict>, z.ZodObject<{
55
+ platform: z.ZodLiteral<"astro">;
56
+ origin: z.ZodString;
57
+ clientId: z.ZodString;
58
+ }, z.core.$strict>]>;
59
+ /**
60
+ * `POST /session/device/app-token`: the platform credential (no bearer;
61
+ * possession is the proof, as at `POST /session/device/token`), the
62
+ * attestation, and optionally `accountId` (pins the account, as that mint's
63
+ * does) and `clientId` (when given, a public client id of the SAME application
64
+ * the attestation names).
65
+ */
66
+ export declare const deviceAppTokenRequestSchema: z.ZodObject<{
67
+ deviceId: z.ZodString;
68
+ deviceSecret: z.ZodString;
69
+ accountId: z.ZodOptional<z.ZodString>;
70
+ clientId: z.ZodOptional<z.ZodString>;
71
+ attestation: z.ZodUnion<readonly [z.ZodObject<{
72
+ platform: z.ZodLiteral<"oxyos">;
73
+ desktopEntryId: z.ZodString;
74
+ }, z.core.$strict>, z.ZodObject<{
75
+ platform: z.ZodEnum<{
76
+ oxyos: "oxyos";
77
+ astro: "astro";
78
+ }>;
79
+ self: z.ZodLiteral<true>;
80
+ }, z.core.$strict>, z.ZodObject<{
81
+ platform: z.ZodLiteral<"astro">;
82
+ origin: z.ZodString;
83
+ clientId: z.ZodString;
84
+ }, z.core.$strict>]>;
85
+ }, z.core.$strict>;
86
+ /**
87
+ * The application's token: a fresh access token of the device's shared session
88
+ * for `accountId`, named for `applicationId` (`azp`, its public client id) and
89
+ * carrying `host`. `expiresAt` is the token's own `exp`
90
+ * ({@link DEVICE_APP_TOKEN_TTL_SECONDS} after it was minted).
91
+ */
92
+ export declare const deviceAppTokenResponseSchema: z.ZodObject<{
93
+ accessToken: z.ZodString;
94
+ expiresAt: z.ZodString;
95
+ applicationId: z.ZodString;
96
+ accountId: z.ZodString;
97
+ }, z.core.$strip>;
98
+ /**
99
+ * The `host` claim of an application token: the platform that vouched for the
100
+ * application and the id of its platform credential. Oxy re-checks both on
101
+ * every request (the credential is live and the platform's, `azp` is a live
102
+ * public client of an active Oxy application).
103
+ */
104
+ export declare const hostTokenClaimSchema: z.ZodObject<{
105
+ platform: z.ZodEnum<{
106
+ oxyos: "oxyos";
107
+ astro: "astro";
108
+ }>;
109
+ credential: z.ZodString;
110
+ }, z.core.$strict>;
111
+ /**
112
+ * What `GET /session/validate-header/:sessionId` adds for an application token:
113
+ * the application it is named for and the platform that vouched for it.
114
+ */
115
+ export declare const hostTokenValidationSchema: z.ZodObject<{
116
+ applicationId: z.ZodString;
117
+ platform: z.ZodEnum<{
118
+ oxyos: "oxyos";
119
+ astro: "astro";
120
+ }>;
121
+ }, z.core.$strip>;
122
+ export type PlatformHost = (typeof PLATFORM_HOSTS)[number];
123
+ export type DeviceAppTokenErrorCode = (typeof DEVICE_APP_TOKEN_ERROR_CODES)[number];
124
+ export type PlatformClient = z.infer<typeof platformClientSchema>;
125
+ export type DeviceAppTokenAttestation = z.infer<typeof deviceAppTokenAttestationSchema>;
126
+ export type DeviceAppTokenRequest = z.infer<typeof deviceAppTokenRequestSchema>;
127
+ export type DeviceAppTokenResponse = z.infer<typeof deviceAppTokenResponseSchema>;
128
+ export type HostTokenClaim = z.infer<typeof hostTokenClaimSchema>;
129
+ export type HostTokenValidation = z.infer<typeof hostTokenValidationSchema>;
@@ -119,8 +119,18 @@ export interface EmailSignInLinkResponse {
119
119
  approved: true;
120
120
  }
121
121
  export declare const emailSignInLinkResponseSchema: z.ZodType<EmailSignInLinkResponse>;
122
- /** `POST /auth/signin/password` */
122
+ /**
123
+ * `POST /auth/signin/password`. `platformClient` is a platform's own sign-in
124
+ * (ADR 0058): see `platformClientSchema`.
125
+ */
123
126
  export declare const passwordSignInRequestSchema: z.ZodObject<{
127
+ platformClient: z.ZodOptional<z.ZodObject<{
128
+ platform: z.ZodEnum<{
129
+ oxyos: "oxyos";
130
+ astro: "astro";
131
+ }>;
132
+ clientId: z.ZodString;
133
+ }, z.core.$strict>>;
124
134
  deviceName: z.ZodOptional<z.ZodString>;
125
135
  deviceFingerprint: z.ZodOptional<z.ZodString>;
126
136
  device: z.ZodOptional<z.ZodObject<{
@@ -131,8 +141,19 @@ export declare const passwordSignInRequestSchema: z.ZodObject<{
131
141
  password: z.ZodString;
132
142
  }, z.core.$strict>;
133
143
  export type PasswordSignInRequest = z.infer<typeof passwordSignInRequestSchema>;
134
- /** `POST /auth/signin/second-factor` */
144
+ /**
145
+ * `POST /auth/signin/second-factor`. A challenge a platform's sign-in received
146
+ * is completed naming the SAME `platformClient`, and one that named none
147
+ * naming none.
148
+ */
135
149
  export declare const secondFactorSignInRequestSchema: z.ZodObject<{
150
+ platformClient: z.ZodOptional<z.ZodObject<{
151
+ platform: z.ZodEnum<{
152
+ oxyos: "oxyos";
153
+ astro: "astro";
154
+ }>;
155
+ clientId: z.ZodString;
156
+ }, z.core.$strict>>;
136
157
  deviceName: z.ZodOptional<z.ZodString>;
137
158
  deviceFingerprint: z.ZodOptional<z.ZodString>;
138
159
  device: z.ZodOptional<z.ZodObject<{
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oxy.so/contracts",
3
- "version": "6.12.0",
3
+ "version": "6.13.0",
4
4
  "description": "OxyHQ API contracts — single source of truth for request/response Zod schemas and inferred types, shared by the backend and the client SDKs",
5
5
  "main": "dist/cjs/index.js",
6
6
  "module": "dist/esm/index.js",
@@ -89,6 +89,6 @@
89
89
  "@types/node": "^26.6.6",
90
90
  "jest": "^30.5.2",
91
91
  "typescript": "~6.0.3",
92
- "@oxy.so/bloom": "17.8.1"
92
+ "@oxy.so/bloom": "17.15.0"
93
93
  }
94
94
  }