@crossworks/client-types 0.400.45 → 0.400.56

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crossworks/client-types",
3
- "version": "0.400.45",
3
+ "version": "0.400.56",
4
4
  "type": "module",
5
5
  "main": "./src/index.ts",
6
6
  "types": "./src/index.ts",
@@ -11,6 +11,7 @@
11
11
  * (`@crossworks/client-types/dto/access-keys`); the brain pins it to its
12
12
  * own list in a test.
13
13
  */
14
+ import type { OidcFreshProof } from './auth';
14
15
  import type { LoginRole } from '../role-names';
15
16
 
16
17
  /** The parts of the brain a key can be limited to. */
@@ -74,7 +75,10 @@ export type AccessKeyList = {
74
75
  * included: a login in the Admin workspace with its keys area (never the
75
76
  * role). Everyone else's keys last at most 90 days. */
76
77
  maxExpiryDays: number | null;
77
- /** Whether the create needs the caller's password: always. */
78
+ /** Whether the create needs the caller's password: always on the wire. A
79
+ * login that GET /api/auth/oidc/status calls `linked` sends `fresh`
80
+ * instead (POST /api/auth/oidc/fresh), or its password where the status
81
+ * says `passwordConfirms`. */
78
82
  needsPassword: boolean;
79
83
  };
80
84
 
@@ -92,6 +96,8 @@ export type AccessKeyCreateInput = {
92
96
  /** The caller's password, when `needsPassword` (never stored, never
93
97
  * logged). */
94
98
  password?: string;
99
+ /** A fresh company sign-in, for a linked login. */
100
+ fresh?: OidcFreshProof;
95
101
  };
96
102
 
97
103
  /** POST /api/access-keys answer (201). `secret` is shown ONCE. */
package/src/dto/agents.ts CHANGED
@@ -98,7 +98,8 @@ export interface AgentParamsDTO {
98
98
  /** How granted tools reach the model. 'deferred' = a stable core in full +
99
99
  * `tool_search` over the rest (same grant, cache-safe). 'map' = the same
100
100
  * core + a tool map naming every other granted tool, called through
101
- * `tool_call`. Absent = 'full'. */
101
+ * `tool_call`. Absent: 'map' for an assistant (role responder or
102
+ * assistant; 'deferred' on a Haiku model), 'full' for any other agent. */
102
103
  tool_loading?: 'full' | 'deferred' | 'map';
103
104
  }
104
105
 
package/src/dto/auth.ts CHANGED
@@ -35,8 +35,11 @@ export type OidcMode = 'off' | 'optional' | 'required';
35
35
 
36
36
  /** GET /api/auth/oidc/config (public, no login). Off: `{ mode: 'off' }`
37
37
  * only, and the client shows no company sign-in at all. Otherwise the
38
- * button's label ("Sign in with {label}"); the button opens
39
- * `GET /api/auth/oidc/start?return=<path>` as a top-level navigation. */
38
+ * button's label ("Sign in with {label}"). A client that holds a bearer
39
+ * (the web app, the desktop app, the phone) opens
40
+ * `GET /api/auth/oidc/start?redirect=<target>&challenge=<S256>` (see
41
+ * OidcHandoff); `?return=<path>` signs the browser itself in with a
42
+ * cookie. */
40
43
  export type OidcConfigDTO = { mode: 'off' } | { mode: 'optional' | 'required'; label: string };
41
44
 
42
45
  /** GET /api/auth/oidc/status (the signed-in login; 401 without one). Off:
@@ -62,17 +65,95 @@ export type OidcStatusDTO =
62
65
  /** DELETE /api/auth/oidc/link is open to it (optional mode, or an
63
66
  * owner or outside login, while linked). */
64
67
  canUnlink: boolean;
68
+ /** A linked login confirms key creation with a fresh sign-in; this says
69
+ * whether it may type its password instead (optional mode, or the
70
+ * original account: a provider can be down). */
71
+ passwordConfirms: boolean;
65
72
  };
66
73
 
67
- /** POST /api/auth/oidc/link { password?, returnTo? }: start a link. Opens
68
- * on the 5-minute ticket a password sign-in on this browser set (used up
69
- * by the start), or on
70
- * the session with the login's password typed again. Navigate the window
71
- * to `url`; the provider returns to the brain, which links and sends the
72
- * browser to `returnTo` with `?oidc=linked` (or `?oidc=<OidcCallbackError>`). */
73
- export type OidcLinkStartBody = { password?: string; returnTo?: string };
74
+ /**
75
+ * Handing a flow to a client that is not the browser's cookie session
76
+ * (docs/oidc-sign-in.md "Handing a sign-in to a client"). The client makes a
77
+ * PKCE verifier (RFC 7636: 43 to 128 unreserved characters), keeps it, and
78
+ * sends its S256 challenge (43 base64url characters) and where the flow ends,
79
+ * one exact URL:
80
+ * - `mantle://oidc`, the desktop app and the phone;
81
+ * - `<origin>/auth/oidc`, the web app's own page, where the origin is this
82
+ * brain's public origin, MANTLE_CLIENT_ORIGIN or a named
83
+ * MANTLE_API_CORS_ORIGINS entry.
84
+ * The browser comes back there with a fragment:
85
+ * `#oidc=code&code=<c>&purpose=<OidcHandoffPurpose>&iss=<brain>`, or
86
+ * `#oidc=<OidcCallbackResult>&iss=<brain>` when the flow stopped. Before
87
+ * spending anything, compare `iss` with the origin the client itself connected
88
+ * to, never with a value a brain told it: a device can hold several brains,
89
+ * and a code from another one must never be sent here. So a client must
90
+ * connect to the brain's public URL (MANTLE_PUBLIC_URL), not an alias.
91
+ * A code lasts 2 minutes, works once and is worth nothing without the
92
+ * verifier. A flow to `mantle://oidc` always asks the person to sign in at the
93
+ * provider, and fails on a provider that sends no `auth_time`.
94
+ */
95
+ export type OidcHandoff = { redirect: string; challenge: string };
96
+ export type OidcHandoffPurpose = 'signin' | 'link' | 'fresh';
97
+
98
+ /** POST /api/auth/oidc/link: start a link.
99
+ *
100
+ * With `handoff` (any client, a bearer one too): opens on the session or a
101
+ * held login, on `ticket` (OidcRefusal.ticket or oidcTicket from a token
102
+ * sign-in), or on the session with the login's password typed again. Open
103
+ * `url` in the browser, then spend the code at POST /api/auth/oidc/exchange:
104
+ * the link is made there.
105
+ *
106
+ * With no `handoff`: the browser's own cookie session. Opens on the 5-minute
107
+ * ticket a password sign-in on this browser set (used up by the start), or
108
+ * on the session with the login's password typed again. Navigate the window
109
+ * to `url`; the provider returns to the brain, which links and sends the
110
+ * browser to `returnTo` with `?oidc=linked` (or `?oidc=<OidcCallbackError>`). */
111
+ export type OidcLinkStartBody = {
112
+ password?: string;
113
+ returnTo?: string;
114
+ handoff?: OidcHandoff;
115
+ ticket?: string;
116
+ };
74
117
  export type OidcLinkStarted = { url: string };
75
118
 
119
+ /** POST /api/auth/oidc/exchange (no login): spend a code from the flow's
120
+ * redirect, for a sign-in or a link. `fresh` codes are not spent here: they
121
+ * go in the request they confirm (OidcFreshProof). */
122
+ export type OidcExchangeBody = { code: string; verifier: string; deviceName?: string };
123
+
124
+ /** A sign-in's answer: a bearer, as POST /api/auth/device-login answers one.
125
+ * It lasts MANTLE_OIDC_SESSION_HOURS and is never rotated: when it ends
126
+ * the person signs in through the provider again. `linked` when a link
127
+ * from a held login signed it in. */
128
+ export type OidcTokenAnswer = {
129
+ token: string;
130
+ expiresIn: number;
131
+ expiresAt: string;
132
+ deviceId: string;
133
+ role: string;
134
+ loginId: string;
135
+ brainId?: string;
136
+ sso: true;
137
+ linked?: true;
138
+ };
139
+ /** A link made for a login that already has its session. */
140
+ export type OidcLinkAnswer = { linked: true };
141
+ export type OidcExchanged = OidcTokenAnswer | OidcLinkAnswer;
142
+
143
+ /** The `code` of a refused exchange: the code is gone (`expired`, also a
144
+ * wrong verifier), the account is another login's (`taken`), or this login
145
+ * already holds another account of the provider (`has-other`). */
146
+ export type OidcExchangeRefusal = { error: string; code: 'expired' | 'taken' | 'has-other' };
147
+
148
+ /** POST /api/auth/oidc/fresh: a linked login confirms who it is with a fresh
149
+ * company sign-in (the provider asks again: prompt=login, max_age=0), in
150
+ * place of its password. Open `url` in the browser, then send the code and
151
+ * the verifier as `fresh` in the request it confirms (OidcFreshProof). */
152
+ export type OidcFreshStartBody = OidcHandoff;
153
+ export type OidcFreshStarted = { url: string };
154
+ /** A fresh sign-in spent on a request: one code, one request. */
155
+ export type OidcFreshProof = { code: string; verifier: string };
156
+
76
157
  /** The `code` of a refused password sign-in (403 from /api/auth/login,
77
158
  * /api/auth/token, /api/auth/device-login and /api/auth/mobile-login), or
78
159
  * of a refused link start:
@@ -80,20 +161,24 @@ export type OidcLinkStarted = { url: string };
80
161
  * - `sso-link-required`: the password was right; link before going on.
81
162
  * The cookie login also set the ticket: show the one "Link your company
82
163
  * sign-in" step, whose button is POST /api/auth/oidc/link with no body.
83
- * The token logins set none: link on the web first.
164
+ * The token logins answer `ticket` instead: send it with the handoff.
84
165
  * - `password-needed`: a link start with no fresh ticket: ask for the
85
166
  * password and send it.
86
167
  * - `already-linked`: the login holds a link already.
87
- * - `sso-session`: POST /api/auth/pair from a session company sign-in
88
- * made: a phone cannot be paired from it yet (it would outlive the
89
- * session); the phone signs in itself. */
168
+ * - `sso-session`: a session company sign-in made cannot do this: pair a
169
+ * phone or a chat, or reset its own password with no old password, since
170
+ * each would outlive the session. The phone signs in itself. */
90
171
  export type OidcRefusalCode =
91
172
  'sso-required' | 'sso-link-required' | 'password-needed' | 'already-linked' | 'sso-session';
92
- export type OidcRefusal = { error: string; code: OidcRefusalCode };
173
+ /** `ticket`: a token login's held ticket on `sso-link-required` (5 minutes,
174
+ * good only to start the link). */
175
+ export type OidcRefusal = { error: string; code: OidcRefusalCode; ticket?: string };
93
176
 
94
177
  /** The `oidc` query value the callback sends the browser back with:
95
178
  * `linked` on a link, else why it stopped. A sign-in that works carries
96
- * none. Failures of a sign-in land on `/login?oidc=<code>`. */
179
+ * none. Failures of a sign-in land on `/login?oidc=<code>`.
180
+ * `wrong-account`: a fresh sign-in used another account than the one
181
+ * linked to this login. */
97
182
  export type OidcCallbackResult =
98
183
  | 'linked'
99
184
  | 'expired'
@@ -103,7 +188,8 @@ export type OidcCallbackResult =
103
188
  | 'not-linked'
104
189
  | 'not-allowed'
105
190
  | 'taken'
106
- | 'has-other';
191
+ | 'has-other'
192
+ | 'wrong-account';
107
193
 
108
194
  /** POST /api/auth/oidc/offer: hide the link offer for 7 days. */
109
195
  export type OidcOfferDismissed = { ok: true; until: string };