@oxy.so/contracts 6.11.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.
Files changed (40) hide show
  1. package/dist/cjs/appAssertions.js +31 -2
  2. package/dist/cjs/client/appAssertions.js +10 -2
  3. package/dist/cjs/client/identityKeyHistory.js +15 -0
  4. package/dist/cjs/client/index.js +15 -4
  5. package/dist/cjs/client/platformSession.js +61 -0
  6. package/dist/cjs/client/userResponse.js +15 -1
  7. package/dist/cjs/identityKeyHistory.js +30 -0
  8. package/dist/cjs/index.js +19 -14
  9. package/dist/cjs/platformSession.js +104 -0
  10. package/dist/cjs/signIn.js +12 -2
  11. package/dist/cjs/userResponse.js +3 -1
  12. package/dist/esm/appAssertions.js +30 -1
  13. package/dist/esm/client/appAssertions.js +10 -2
  14. package/dist/esm/client/identityKeyHistory.js +12 -0
  15. package/dist/esm/client/index.js +3 -0
  16. package/dist/esm/client/platformSession.js +58 -0
  17. package/dist/esm/client/userResponse.js +14 -0
  18. package/dist/esm/identityKeyHistory.js +27 -0
  19. package/dist/esm/index.js +4 -1
  20. package/dist/esm/platformSession.js +97 -0
  21. package/dist/esm/signIn.js +12 -2
  22. package/dist/esm/userResponse.js +3 -1
  23. package/dist/types/appAssertions.d.ts +40 -1
  24. package/dist/types/client/appAssertions.d.ts +11 -4
  25. package/dist/types/client/identityKeyHistory.d.ts +13 -0
  26. package/dist/types/client/index.d.ts +6 -0
  27. package/dist/types/client/platformSession.d.ts +50 -0
  28. package/dist/types/client/userResponse.d.ts +7 -0
  29. package/dist/types/identityKeyHistory.d.ts +22 -0
  30. package/dist/types/index.d.ts +5 -1
  31. package/dist/types/inference/embeddings.d.ts +4 -4
  32. package/dist/types/inference/errors.d.ts +4 -4
  33. package/dist/types/inference/inbox.d.ts +2 -2
  34. package/dist/types/inference/realtime.d.ts +4 -4
  35. package/dist/types/inference/streamEvents.d.ts +4 -4
  36. package/dist/types/oxyRecordTypes.d.ts +1 -1
  37. package/dist/types/platformSession.d.ts +129 -0
  38. package/dist/types/signIn.d.ts +23 -2
  39. package/dist/types/userResponse.d.ts +18 -0
  40. package/package.json +2 -2
@@ -0,0 +1,104 @@
1
+ "use strict";
2
+ /**
3
+ * A platform that holds the Oxy session (ADR 0058).
4
+ *
5
+ * OxyOS (`oxyos-accountd`) and Astro hold the person's Oxy session on a
6
+ * PLATFORM CREDENTIAL: a device holder credential issued to the platform's own
7
+ * sign-in, the one that names it with {@link platformClientSchema}
8
+ * (`POST /auth/signin/password`, completed by `POST /auth/signin/second-factor`).
9
+ * Applications they run hold nothing; the platform asks
10
+ * `POST /session/device/app-token` for a five-minute token named for each one
11
+ * (`azp`, and the `host` claim naming the platform and its credential).
12
+ *
13
+ * The Zod-free half (vocabularies, the response check) is
14
+ * `./client/platformSession.ts`.
15
+ */
16
+ Object.defineProperty(exports, "__esModule", { value: true });
17
+ exports.hostTokenValidationSchema = exports.hostTokenClaimSchema = exports.deviceAppTokenResponseSchema = exports.deviceAppTokenRequestSchema = exports.deviceAppTokenAttestationSchema = exports.platformClientSchema = exports.PLATFORM_HOSTS = exports.OXYOS_DESKTOP_ENTRY_ID_PATTERN = exports.DEVICE_APP_TOKEN_TTL_SECONDS = exports.DEVICE_APP_TOKEN_ERROR_CODES = exports.APP_TOKEN_DEVICE_ACCESS_DENIED = void 0;
18
+ const zod_1 = require("zod");
19
+ const appAssertions_1 = require("./appAssertions");
20
+ const platformSession_1 = require("./client/platformSession");
21
+ Object.defineProperty(exports, "APP_TOKEN_DEVICE_ACCESS_DENIED", { enumerable: true, get: function () { return platformSession_1.APP_TOKEN_DEVICE_ACCESS_DENIED; } });
22
+ Object.defineProperty(exports, "DEVICE_APP_TOKEN_ERROR_CODES", { enumerable: true, get: function () { return platformSession_1.DEVICE_APP_TOKEN_ERROR_CODES; } });
23
+ Object.defineProperty(exports, "DEVICE_APP_TOKEN_TTL_SECONDS", { enumerable: true, get: function () { return platformSession_1.DEVICE_APP_TOKEN_TTL_SECONDS; } });
24
+ Object.defineProperty(exports, "OXYOS_DESKTOP_ENTRY_ID_PATTERN", { enumerable: true, get: function () { return platformSession_1.OXYOS_DESKTOP_ENTRY_ID_PATTERN; } });
25
+ Object.defineProperty(exports, "PLATFORM_HOSTS", { enumerable: true, get: function () { return platformSession_1.PLATFORM_HOSTS; } });
26
+ const stringChecks_1 = require("./stringChecks");
27
+ const publicClientIdSchema = zod_1.z.string().check((0, stringChecks_1.utf16MinLength)(1)).check((0, stringChecks_1.utf16MaxLength)(256));
28
+ /**
29
+ * Names the platform on its own password sign-in, and on the second factor
30
+ * completing it. Honoured only when the request has NO web `Origin` and
31
+ * `clientId` is a live public client id of an active Oxy application whose
32
+ * registry entry declares `platformHost` equal to `platform`; anything else is
33
+ * refused with the ordinary invalid-request answer before any account lookup or
34
+ * password work. When honoured, the device credential the sign-in returns is a
35
+ * platform credential, and a credential the sign-in's `device` proof presented
36
+ * is retired.
37
+ */
38
+ exports.platformClientSchema = zod_1.z.strictObject({
39
+ platform: appAssertions_1.platformHostSchema,
40
+ clientId: publicClientIdSchema,
41
+ });
42
+ /**
43
+ * Which application the token is for, as the platform vouches for it:
44
+ *
45
+ * - `{ platform: 'oxyos', desktopEntryId }`: an application OxyOS launched,
46
+ * by the desktop entry id its registry entry declares;
47
+ * - `{ platform, self: true }`: the platform's own application (OxyOS's
48
+ * Settings and shell, Astro's chrome);
49
+ * - `{ platform: 'astro', origin, clientId }`: an Oxy web application Astro
50
+ * shows, by the exact origin it committed and the application's client id.
51
+ */
52
+ exports.deviceAppTokenAttestationSchema = zod_1.z.union([
53
+ zod_1.z.strictObject({ platform: zod_1.z.literal('oxyos'), desktopEntryId: appAssertions_1.oxyosDesktopEntryIdSchema }),
54
+ zod_1.z.strictObject({ platform: appAssertions_1.platformHostSchema, self: zod_1.z.literal(true) }),
55
+ zod_1.z.strictObject({
56
+ platform: zod_1.z.literal('astro'),
57
+ origin: appAssertions_1.applicationWebOriginSchema,
58
+ clientId: publicClientIdSchema,
59
+ }),
60
+ ]);
61
+ /**
62
+ * `POST /session/device/app-token`: the platform credential (no bearer;
63
+ * possession is the proof, as at `POST /session/device/token`), the
64
+ * attestation, and optionally `accountId` (pins the account, as that mint's
65
+ * does) and `clientId` (when given, a public client id of the SAME application
66
+ * the attestation names).
67
+ */
68
+ exports.deviceAppTokenRequestSchema = zod_1.z.strictObject({
69
+ deviceId: zod_1.z.string().check((0, stringChecks_1.utf16MinLength)(1)).check((0, stringChecks_1.utf16MaxLength)(128)),
70
+ deviceSecret: zod_1.z.string().check((0, stringChecks_1.utf16MinLength)(1)).check((0, stringChecks_1.utf16MaxLength)(256)),
71
+ accountId: zod_1.z.string().check((0, stringChecks_1.utf16MinLength)(1)).check((0, stringChecks_1.utf16MaxLength)(128)).optional(),
72
+ clientId: publicClientIdSchema.optional(),
73
+ attestation: exports.deviceAppTokenAttestationSchema,
74
+ });
75
+ /**
76
+ * The application's token: a fresh access token of the device's shared session
77
+ * for `accountId`, named for `applicationId` (`azp`, its public client id) and
78
+ * carrying `host`. `expiresAt` is the token's own `exp`
79
+ * ({@link DEVICE_APP_TOKEN_TTL_SECONDS} after it was minted).
80
+ */
81
+ exports.deviceAppTokenResponseSchema = zod_1.z.object({
82
+ accessToken: zod_1.z.string().check((0, stringChecks_1.utf16MinLength)(1)),
83
+ expiresAt: zod_1.z.string().check((0, stringChecks_1.isoDateTime)()),
84
+ applicationId: zod_1.z.string().check((0, stringChecks_1.utf16MinLength)(1)),
85
+ accountId: zod_1.z.string().check((0, stringChecks_1.utf16MinLength)(1)),
86
+ });
87
+ /**
88
+ * The `host` claim of an application token: the platform that vouched for the
89
+ * application and the id of its platform credential. Oxy re-checks both on
90
+ * every request (the credential is live and the platform's, `azp` is a live
91
+ * public client of an active Oxy application).
92
+ */
93
+ exports.hostTokenClaimSchema = zod_1.z.strictObject({
94
+ platform: appAssertions_1.platformHostSchema,
95
+ credential: zod_1.z.string().check((0, stringChecks_1.utf16MinLength)(1)).check((0, stringChecks_1.utf16MaxLength)(128)),
96
+ });
97
+ /**
98
+ * What `GET /session/validate-header/:sessionId` adds for an application token:
99
+ * the application it is named for and the platform that vouched for it.
100
+ */
101
+ exports.hostTokenValidationSchema = zod_1.z.object({
102
+ applicationId: zod_1.z.string().check((0, stringChecks_1.utf16MinLength)(1)),
103
+ platform: appAssertions_1.platformHostSchema,
104
+ });
@@ -39,6 +39,7 @@ const stringChecks_1 = require("./stringChecks");
39
39
  const zod_1 = require("zod");
40
40
  const accountEmail_1 = require("./accountEmail");
41
41
  const deviceSession_1 = require("./deviceSession");
42
+ const platformSession_1 = require("./platformSession");
42
43
  // The Zod-free half of this contract lives in `./client/` (`@oxy.so/contracts/client`);
43
44
  // it is re-exported here so the root entry is unchanged.
44
45
  const signIn_1 = require("./client/signIn");
@@ -170,20 +171,29 @@ exports.emailSignInLinkRequestSchema = zod_1.z
170
171
  exports.emailSignInLinkResponseSchema = zod_1.z.object({
171
172
  approved: zod_1.z.literal(true),
172
173
  });
173
- /** `POST /auth/signin/password` */
174
+ /**
175
+ * `POST /auth/signin/password`. `platformClient` is a platform's own sign-in
176
+ * (ADR 0058): see `platformClientSchema`.
177
+ */
174
178
  exports.passwordSignInRequestSchema = zod_1.z
175
179
  .object({
176
180
  identifier: exports.signInIdentifierSchema,
177
181
  password: exports.passwordInputSchema,
178
182
  ...sessionEnvelope,
183
+ platformClient: platformSession_1.platformClientSchema.optional(),
179
184
  })
180
185
  .strict();
181
- /** `POST /auth/signin/second-factor` */
186
+ /**
187
+ * `POST /auth/signin/second-factor`. A challenge a platform's sign-in received
188
+ * is completed naming the SAME `platformClient`, and one that named none
189
+ * naming none.
190
+ */
182
191
  exports.secondFactorSignInRequestSchema = zod_1.z
183
192
  .object({
184
193
  challengeId: opaqueTokenSchema,
185
194
  code: exports.secondFactorCodeSchema,
186
195
  ...sessionEnvelope,
196
+ platformClient: platformSession_1.platformClientSchema.optional(),
187
197
  })
188
198
  .strict();
189
199
  /** `POST /auth/signup` — the account, from a username and a confirmed email. */
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.deviceLinkedSessionsResponseSchema = exports.deviceLinkedSessionSchema = exports.currentUserResponseSchema = exports.userProfileUpdateSchema = exports.userResponseSchema = exports.dateOfBirthSchema = exports.themePreferenceSchema = exports.userRelationshipSchema = exports.userNameSchema = void 0;
3
+ exports.deviceLinkedSessionsResponseSchema = exports.deviceLinkedSessionSchema = exports.currentUserResponseSchema = exports.userProfileUpdateSchema = exports.pronounsSchema = exports.userResponseSchema = exports.dateOfBirthSchema = exports.themePreferenceSchema = exports.userRelationshipSchema = exports.userNameSchema = void 0;
4
4
  exports.resolveUserId = resolveUserId;
5
5
  exports.safeParseContract = safeParseContract;
6
6
  const stringChecks_1 = require("./stringChecks");
@@ -248,6 +248,7 @@ exports.userResponseSchema = zod_1.z
248
248
  .optional(),
249
249
  })
250
250
  .passthrough();
251
+ exports.pronounsSchema = zod_1.z.enum(userResponse_1.PRONOUNS);
251
252
  exports.userProfileUpdateSchema = zod_1.z
252
253
  .object({
253
254
  name: zod_1.z
@@ -267,6 +268,7 @@ exports.userProfileUpdateSchema = zod_1.z
267
268
  avatar: zod_1.z.string().optional(),
268
269
  color: zod_1.z.string().nullable().optional(),
269
270
  bio: zod_1.z.string().optional(),
271
+ pronouns: exports.pronounsSchema.optional(),
270
272
  description: zod_1.z.string().optional(),
271
273
  phone: zod_1.z.string().optional(),
272
274
  address: zod_1.z.string().optional(),
@@ -25,6 +25,7 @@ import { isoDateTime, utf16MaxLength, utf16MinLength } from './stringChecks.js';
25
25
  */
26
26
  import { z } from 'zod';
27
27
  import { APP_ASSERTION_CHALLENGE_PURPOSES, APP_ASSERTION_ERROR_CODES, APP_ASSERTION_PLATFORMS, OXY_APP_ASSERTION_AUDIENCE, OXY_APP_ASSERTION_HEADER, OXY_APP_ASSERTION_TTL_SECONDS, OXY_APP_ASSERTION_TYPE, } from './client/appAssertions.js';
28
+ import { OXYOS_DESKTOP_ENTRY_ID_PATTERN, PLATFORM_HOSTS } from './client/platformSession.js';
28
29
  export { APP_ASSERTION_CHALLENGE_PURPOSES, APP_ASSERTION_ERROR_CODES, APP_ASSERTION_PLATFORMS, OXY_APP_ASSERTION_AUDIENCE, OXY_APP_ASSERTION_HEADER, OXY_APP_ASSERTION_TTL_SECONDS, OXY_APP_ASSERTION_TYPE, };
29
30
  const applicationIdSchema = z.string().trim().check(utf16MinLength(1)).check(utf16MaxLength(255));
30
31
  const base64Url32Schema = z.string().regex(/^[A-Za-z0-9_-]{43}$/);
@@ -34,6 +35,8 @@ const base64Schema = (max) => z
34
35
  .check(utf16MaxLength(max))
35
36
  .regex(/^[A-Za-z0-9+/]+={0,2}$/);
36
37
  export const appAssertionPlatformSchema = z.enum(APP_ASSERTION_PLATFORMS);
38
+ /** A platform that holds the Oxy session for the applications it runs (ADR 0058). */
39
+ export const platformHostSchema = z.enum(PLATFORM_HOSTS);
37
40
  export const appAssertionErrorCodeSchema = z.enum(APP_ASSERTION_ERROR_CODES);
38
41
  // ---------------------------------------------------------------------------
39
42
  // Registry
@@ -69,6 +72,11 @@ export const appleBundleIdSchema = z
69
72
  .string()
70
73
  .check(utf16MaxLength(255))
71
74
  .regex(/^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/, 'Must be an Apple bundle id');
75
+ /** An OxyOS desktop entry id (`so.oxy.dropsea`), the id OxyOS launches the application by. */
76
+ export const oxyosDesktopEntryIdSchema = z
77
+ .string()
78
+ .check(utf16MaxLength(255))
79
+ .regex(OXYOS_DESKTOP_ENTRY_ID_PATTERN, 'Must be an OxyOS desktop entry id');
72
80
  const unique = (values) => new Set(values).size === values.length;
73
81
  export const applicationAndroidRecognitionSchema = z
74
82
  .object({
@@ -83,9 +91,22 @@ export const applicationAndroidRecognitionSchema = z
83
91
  export const applicationIosRecognitionSchema = z
84
92
  .object({ teamId: appleTeamIdSchema, bundleId: appleBundleIdSchema })
85
93
  .strict();
94
+ const oxyosDesktopEntryIdsSchema = z
95
+ .array(oxyosDesktopEntryIdSchema)
96
+ .max(20)
97
+ .refine(unique, 'Desktop entry ids must be unique');
86
98
  /**
87
99
  * What Oxy staff write for an application: the whole declaration, replaced at
88
100
  * once. `null` and `[]` declare nothing for that platform.
101
+ *
102
+ * ADR 0058 adds two fields a writer may omit, and an omitted one is left as
103
+ * the registry holds it (a writer that predates them cannot erase them):
104
+ *
105
+ * - `platformHost`: this application IS a platform that holds the Oxy session
106
+ * (OxyOS, Astro). Its public client id is the one a platform's own sign-in
107
+ * names (`platformClient`), and only an Oxy application may declare it.
108
+ * - `oxyosDesktopEntryIds`: the OxyOS desktop entry ids that launch this
109
+ * application, each naming one application only, as a web origin does.
89
110
  */
90
111
  export const applicationRecognitionWriteSchema = z
91
112
  .object({
@@ -95,12 +116,16 @@ export const applicationRecognitionWriteSchema = z
95
116
  .refine(unique, 'Origins must be unique'),
96
117
  android: applicationAndroidRecognitionSchema.nullable(),
97
118
  ios: applicationIosRecognitionSchema.nullable(),
119
+ platformHost: platformHostSchema.nullable().optional(),
120
+ oxyosDesktopEntryIds: oxyosDesktopEntryIdsSchema.optional(),
98
121
  })
99
122
  .strict();
100
123
  /** An application's recognition as the registry holds it; `updatedAt` is `null` when none was written. */
101
124
  export const applicationRecognitionSchema = applicationRecognitionWriteSchema
102
125
  .extend({
103
126
  applicationId: applicationIdSchema,
127
+ platformHost: platformHostSchema.nullable(),
128
+ oxyosDesktopEntryIds: oxyosDesktopEntryIdsSchema,
104
129
  updatedAt: z.string().check(isoDateTime()).nullable(),
105
130
  })
106
131
  .strict();
@@ -151,10 +176,14 @@ export const appAttestKeyResponseSchema = z.object({ keyId: appAttestKeyIdSchema
151
176
  * `POST /apps/assertions`. The body names the application and the platform;
152
177
  * the proof is the platform's: none on the web (the browser's `Origin` is), a
153
178
  * Play Integrity token on Android, an App Attest assertion on iOS, each over a
154
- * challenge minted for `assertion`.
179
+ * challenge minted for `assertion`. On `oxyos` and `astro` the bearer is the
180
+ * proof: an application token that platform minted for this application
181
+ * (ADR 0058).
155
182
  */
156
183
  export const appAssertionRequestSchema = z.discriminatedUnion('platform', [
157
184
  z.object({ applicationId: applicationIdSchema, platform: z.literal('web') }).strict(),
185
+ z.object({ applicationId: applicationIdSchema, platform: z.literal('oxyos') }).strict(),
186
+ z.object({ applicationId: applicationIdSchema, platform: z.literal('astro') }).strict(),
158
187
  z
159
188
  .object({
160
189
  applicationId: applicationIdSchema,
@@ -10,8 +10,12 @@
10
10
  * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
11
11
  */
12
12
  import { datetime, exact, oneOf, optional, pattern, strictObject, string } from './check.js';
13
- /** How an app proves itself: the browser's origin, Play Integrity, or App Attest. */
14
- export const APP_ASSERTION_PLATFORMS = ['web', 'android', 'ios'];
13
+ /**
14
+ * How an app proves itself: the browser's origin, Play Integrity, App Attest,
15
+ * or (`oxyos`, `astro`) an application token the platform holding the session
16
+ * minted for it (ADR 0058), whose bearer is the proof.
17
+ */
18
+ export const APP_ASSERTION_PLATFORMS = ['web', 'android', 'ios', 'oxyos', 'astro'];
15
19
  /**
16
20
  * What a device challenge is spent on: an assertion, or (iOS only) registering
17
21
  * an App Attest key. A challenge minted for one is refused for the other.
@@ -42,6 +46,9 @@ export const OXY_APP_ASSERTION_TTL_SECONDS = 300;
42
46
  * - `attestation_invalid`: the App Attest attestation does not verify.
43
47
  * - `assertion_invalid`: the App Attest assertion does not verify, or its counter did not advance.
44
48
  * - `signing_unavailable`: Oxy cannot sign (503).
49
+ * - `app_token_mismatch`: an `oxyos` or `astro` assertion needs an application token that
50
+ * platform minted for this application; an application token gets an assertion for its own
51
+ * application and platform only.
45
52
  */
46
53
  export const APP_ASSERTION_ERROR_CODES = [
47
54
  'application_unavailable',
@@ -57,6 +64,7 @@ export const APP_ASSERTION_ERROR_CODES = [
57
64
  'attestation_invalid',
58
65
  'assertion_invalid',
59
66
  'signing_unavailable',
67
+ 'app_token_mismatch',
60
68
  ];
61
69
  /** 32 random bytes, base64url: a challenge, or the SHA-256 it is bound into. */
62
70
  const BASE64URL_32 = /^[A-Za-z0-9_-]{43}$/;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * A personal account's key history (`GET /identity/key-history`), without Zod.
3
+ * Schema: `../identityKeyHistory.ts`.
4
+ *
5
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
6
+ */
7
+ import { array, datetime, exact, nullable, pattern, strictObject, string } from './check.js';
8
+ const canonicalPublicKey = string(pattern(/^04[0-9a-f]{128}$/));
9
+ export const identityKeyHistoryCheck = exact()(strictObject({
10
+ publicKey: nullable(canonicalPublicKey),
11
+ retired: array(strictObject({ publicKey: canonicalPublicKey, retiredAt: string(datetime) })),
12
+ }));
@@ -27,6 +27,7 @@ export { signedRecordEnvelopeCheck } from './identity.js';
27
27
  export { DOMAIN_NAME_MAX_LENGTH, normalizeDomainName } from './domainName.js';
28
28
  export { deviceActivateResponseCheck, deviceDirectoryCheck, deviceDirectorySyncCheck, } from './deviceDirectory.js';
29
29
  export { SESSION_ACCOUNTS_CHANGED_EVENT, activeTokenCheck, deviceBackgroundCredentialResponseCheck, deviceContextTokenV1RequestCheck, deviceContextTokenV1ResponseCheck, holderContextEvidenceV1RequestCheck, holderContextEvidenceV1ResponseCheck, deviceJoinCodeResponseCheck, deviceJoinResponseCheck, deviceRegisterResponseCheck, deviceSessionStateCheck, deviceSessionSyncCheck, deviceTokenMintResponseCheck, sessionAccountsChangedEventCheck, } from './deviceSession.js';
30
+ export { identityKeyHistoryCheck } from './identityKeyHistory.js';
30
31
  export { IDENTITY_LINK_QR_PREFIX, IDENTITY_LINK_STATUSES, buildIdentityLinkQrPayload, identityLinkCreateResponseCheck, identityLinkStateCheck, parseIdentityLinkQrPayload, } from './identityLink.js';
31
32
  export { IDENTITY_ERROR_CODES, IDENTITY_PROOF_ACTIONS, IDENTITY_PROOF_ACTION_VALUES, IDENTITY_PROOF_AUDIENCE, IDENTITY_PROOF_CHALLENGE_TTL_MS, IDENTITY_PROOF_DOMAIN, IDENTITY_PROOF_VERSION, buildIdentityProofMessage, canonicalJson, } from './identityProof.js';
32
33
  export { ORGANIZATION_ALIAS_KINDS, ORGANIZATION_CLAIM_DECISIONS, ORGANIZATION_CLAIM_STATUSES, ORGANIZATION_ERROR_CODES, ORGANIZATION_NAME_MAX_LENGTH, ORGANIZATION_STATUSES, ORGANIZATION_TYPES, createOrganizationCheck, organizationBatchCheck, organizationCheck, organizationClaimCheck, organizationClaimDetailCheck, organizationClaimInputCheck, organizationClaimListCheck, organizationClaimReviewCheck, organizationCurationResultCheck, organizationExternalCheck, organizationExternalResolutionCheck, organizationImportBatchResultCheck, organizationListCheck, organizationNameCheck, updateOrganizationCheck, } from './organizations.js';
@@ -39,8 +40,10 @@ export { CONSOLE_TERMS_VERSION, CONSOLE_USE_CASES, } from './consoleOnboarding.j
39
40
  export { EMAIL_ACCOUNTS_MAX, EMAIL_SIGNIN_CHOICE_TTL_MS, EMAIL_SIGNIN_LINK_TTL_MS, EMAIL_SIGNIN_LONG_CODE_ALPHABET, EMAIL_SIGNIN_LONG_CODE_LENGTH, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, REAUTH_ACTIONS, SECOND_FACTOR_CODE_MAX_LENGTH, SIGN_IN_IDENTIFIER_MAX_LENGTH, SIGNIN_SECOND_FACTOR_MAX_ATTEMPTS, SIGNIN_SECOND_FACTOR_TTL_MS, SIGN_IN_ERROR_CODES, TOTP_BACKUP_CODE_COUNT, TOTP_DIGITS, TOTP_PERIOD_SECONDS, emailSignInChooseAccountCheck, emailSignInLinkResponseCheck, emailSignInPendingCheck, emailSignInStartResponseCheck, isEmailSignInChooseAccount, isSecondFactorRequired, normalizeEmailSignInCode, reauthProofCheck, secondFactorRequiredCheck, signInMethodsCheck, totpBackupCodesResponseCheck, totpEnrollResponseCheck, } from './signIn.js';
40
41
  export { BOT_USERNAME_INVALID_MESSAGE, BOT_USERNAME_SUFFIX, NUMERIC_USERNAME_MESSAGE, RESERVED_USERNAMES, RESERVED_USERNAME_MESSAGE, USERNAME_INVALID_MESSAGE, USERNAME_MAX_LENGTH, USERNAME_MIN_LENGTH, USERNAME_PATTERN_SOURCE, applyBotUsernameSuffix, botUsernameCheck, stripDisallowedUsernameCharacters, usernameCheck, usernameCheckForAccountKind, } from './username.js';
41
42
  export { userNameCheck, PROFILE_LINKS_MAX, PROFILE_LINK_TITLE_MAX } from './userResponse.js';
43
+ export { PRONOUNS } from './userResponse.js';
42
44
  export { CLAIMANT_RELATIONSHIPS, CLOSED_CONTENT_CLAIM_STATES, CONTENT_CLAIM_COUNTER_NOTICE_LIMITS, CONTENT_CLAIM_ERROR_CODES, CONTENT_CLAIM_KINDS, CONTENT_CLAIM_LIMITS, CONTENT_CLAIM_REFERENCE_PATTERN, CONTENT_CLAIM_STATES, COUNTER_NOTICE_STATEMENT_VERSION, COUNTER_NOTICE_STATEMENTS, ERASURE_REQUEST_DEADLINE_DAYS, OPEN_CONTENT_CLAIM_STATES, isErasureRequest, isRightsClaim, } from './contentClaims.js';
43
45
  export { APP_ASSERTION_CHALLENGE_PURPOSES, APP_ASSERTION_ERROR_CODES, APP_ASSERTION_PLATFORMS, OXY_APP_ASSERTION_AUDIENCE, OXY_APP_ASSERTION_HEADER, OXY_APP_ASSERTION_TTL_SECONDS, OXY_APP_ASSERTION_TYPE, appAssertionChallengeResponseCheck, appAssertionResponseCheck, appAttestKeyResponseCheck, } from './appAssertions.js';
46
+ export { APP_TOKEN_DEVICE_ACCESS_DENIED, DEVICE_APP_TOKEN_ERROR_CODES, DEVICE_APP_TOKEN_TTL_SECONDS, OXYOS_DESKTOP_ENTRY_ID_PATTERN, PLATFORM_HOSTS, deviceAppTokenResponseCheck, } from './platformSession.js';
44
47
  export { USER_PROFILE_COLORS, USER_PROFILE_COLOR_PRESETS, FREE_USER_PROFILE_COLOR_PRESETS, } from '../profileColors.generated.js';
45
48
  export * from '../products/one.js';
46
49
  export { CAMPAIGN_LABEL_MAX_LENGTH, CAMPAIGN_CLICK_ID_MAX_LENGTH, hasCampaignControlCharacters, } from './campaignAttribution.js';
@@ -0,0 +1,58 @@
1
+ /**
2
+ * A platform that holds the Oxy session (ADR 0058), without Zod. Schemas:
3
+ * `../platformSession.ts`.
4
+ *
5
+ * OxyOS and Astro hold the person's Oxy session themselves, on a PLATFORM
6
+ * CREDENTIAL, and ask Oxy for a short token named for each application they
7
+ * run (`POST /session/device/app-token`). Applications hold no credential.
8
+ *
9
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
10
+ */
11
+ import { datetime, exact, minLength, object, string } from './check.js';
12
+ /** The platforms that hold the Oxy session for the applications they run. */
13
+ export const PLATFORM_HOSTS = ['oxyos', 'astro'];
14
+ /**
15
+ * An OxyOS desktop entry id (`so.oxy.dropsea`): the reverse-DNS id OxyOS names
16
+ * an application by in its registry and launch records. Lowercase, at least two
17
+ * segments, unique across applications like a web origin.
18
+ */
19
+ export const OXYOS_DESKTOP_ENTRY_ID_PATTERN = /^[a-z0-9]+(\.[a-z0-9-]+)+$/;
20
+ /** An application token lives exactly this long (ADR 0058 2.3). */
21
+ export const DEVICE_APP_TOKEN_TTL_SECONDS = 300;
22
+ /**
23
+ * Why `POST /session/device/app-token` refused. The API answers `{ error: <code> }`.
24
+ *
25
+ * - `invalid_request` (400): the body is not the contract's.
26
+ * - `browser_not_allowed` (403): the request carries a web `Origin` (or
27
+ * `Sec-Fetch-Site`); only a platform's own native service mints.
28
+ * - `invalid_device_secret` (401): the secret proves no PLATFORM credential of
29
+ * that device. A wrong secret counts toward the device-secret lockout.
30
+ * - `application_not_recognised` (403): the credential is another platform's,
31
+ * or the attestation names no active Oxy application recognised for this
32
+ * platform (an unknown desktop entry id, an origin that is not the
33
+ * application's, auth.oxy.so's application, a third-party application, a
34
+ * `clientId` of another application).
35
+ * - `no_active_session` / `account_not_on_device` (401): as
36
+ * `POST /session/device/token`: nothing live to mint for, or the pinned
37
+ * account is not live on the device.
38
+ */
39
+ export const DEVICE_APP_TOKEN_ERROR_CODES = [
40
+ 'invalid_request',
41
+ 'browser_not_allowed',
42
+ 'invalid_device_secret',
43
+ 'application_not_recognised',
44
+ 'no_active_session',
45
+ 'account_not_on_device',
46
+ ];
47
+ /**
48
+ * Every bearer-authenticated `/session/device/*` route answers an application
49
+ * token (one carrying `host`) with `403 { error: APP_TOKEN_DEVICE_ACCESS_DENIED }`:
50
+ * the device is the platform's, never an application's.
51
+ */
52
+ export const APP_TOKEN_DEVICE_ACCESS_DENIED = 'app_token_device_access_denied';
53
+ export const deviceAppTokenResponseCheck = exact()(object({
54
+ accessToken: string(minLength(1)),
55
+ expiresAt: string(datetime),
56
+ applicationId: string(minLength(1)),
57
+ accountId: string(minLength(1)),
58
+ }));
@@ -14,6 +14,20 @@ export const userNameCheck = exact()(looseObject({
14
14
  * Most links a profile may show. Enforced by the server on every write that
15
15
  * carries `linksMetadata` (see `user.service.ts`), and by the editor.
16
16
  */
17
+ /**
18
+ * How an account names its pronouns: one of a closed list, never free text. A
19
+ * federated account's source value is mapped onto it; a value that maps to none
20
+ * of these is `unspecified`.
21
+ */
22
+ export const PRONOUNS = [
23
+ 'unspecified',
24
+ 'he_him',
25
+ 'she_her',
26
+ 'they_them',
27
+ 'he_they',
28
+ 'she_they',
29
+ 'it_its',
30
+ ];
17
31
  export const PROFILE_LINKS_MAX = 10;
18
32
  /**
19
33
  * Longest title an editor may give a profile link, in characters. Not enforced
@@ -0,0 +1,27 @@
1
+ /**
2
+ * A personal account's key history: `GET /identity/key-history`.
3
+ *
4
+ * The current root (`null` without one) and every root a rotation replaced,
5
+ * oldest first. Commons reads it to accept a previous recovery phrase only when
6
+ * it derives a key that WAS this account's root, and keeps that key to spend
7
+ * what it received. A retired root is never any account's again (ADR 0061 D2).
8
+ *
9
+ * Keys are canonical: uncompressed, lowercase (`04` + 128 hex). No private key
10
+ * or phrase crosses this contract.
11
+ *
12
+ * The Zod-free check is `./client/identityKeyHistory.ts`.
13
+ */
14
+ import { z } from 'zod';
15
+ import { isoDateTime } from './stringChecks.js';
16
+ const canonicalPublicKey = z.string().regex(/^04[0-9a-f]{128}$/);
17
+ export const identityKeyHistorySchema = z
18
+ .object({
19
+ publicKey: canonicalPublicKey.nullable(),
20
+ retired: z.array(z
21
+ .object({
22
+ publicKey: canonicalPublicKey,
23
+ retiredAt: z.string().check(isoDateTime()),
24
+ })
25
+ .strict()),
26
+ })
27
+ .strict();
package/dist/esm/index.js CHANGED
@@ -14,7 +14,7 @@ export { ACCOUNT_NAME_POLICY_BY_KIND, ACCOUNT_TITLE_DISALLOWED_SOURCE, ACCOUNT_T
14
14
  export { AVATAR_EYE_SPACING, AVATAR_PICKABLE_COLORS, AVATAR_PICKABLE_SHAPES, avatarCharacterFor, avatarCharacterSchema, parseAvatarCharacter, } from './avatarCharacter.js';
15
15
  export { ACCOUNT_ACTOR_NATURES, ACCOUNT_SUBJECT_CONTRACT_VERSION, FINANCIAL_EFFECT_DIRECTIONS, KIND_INDEPENDENT_ACCOUNT_DIMENSIONS, accountActorChainFromSession, accountActorChainSchema, accountActorNatureSchema, accountKindActorNature, accountKindActsAsItself, attributeFinancialEffect, financialEffectAttributionSchema, } from './accountSubject.js';
16
16
  export { usernameSchema, usernameSchemaForAccountKind, isValidUsername, stripDisallowedUsernameCharacters, applyBotUsernameSuffix, USERNAME_MIN_LENGTH, USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE, BOT_USERNAME_INVALID_MESSAGE, RESERVED_USERNAME_MESSAGE, NUMERIC_USERNAME_MESSAGE, } from './username.js';
17
- export { PROFILE_LINKS_MAX, PROFILE_LINK_TITLE_MAX } from './client/userResponse.js';
17
+ export { PRONOUNS, PROFILE_LINKS_MAX, PROFILE_LINK_TITLE_MAX } from './client/userResponse.js';
18
18
  export {
19
19
  // Schemas
20
20
  userNameSchema, userRelationshipSchema, themePreferenceSchema, dateOfBirthSchema, userResponseSchema, userProfileUpdateSchema, currentUserResponseSchema, deviceLinkedSessionSchema, deviceLinkedSessionsResponseSchema,
@@ -81,6 +81,8 @@ loginResultSchema, } from './deviceBoot.js';
81
81
  export {
82
82
  // Schemas
83
83
  rotateKeyChallengeResponseSchema, rotateKeyCompleteRequestSchema, rotateKeyCompleteResponseSchema, } from './keyRotation.js';
84
+ // A personal account's current root and the roots rotation replaced
85
+ export { identityKeyHistorySchema } from './identityKeyHistory.js';
84
86
  export {
85
87
  // Schemas — encrypted off-device identity backup (b3 Feature 1)
86
88
  backupLookupIdSchema, encryptedBackupEnvelopeSchema, backupUploadRequestSchema, backupStatusResponseSchema, } from './keyRecovery.js';
@@ -209,6 +211,7 @@ export * from './serviceToken.js';
209
211
  export * from './applicationRoles.js';
210
212
  export * from './contentClaims.js';
211
213
  export * from './appAssertions.js';
214
+ export * from './platformSession.js';
212
215
  export * from './products/one.js';
213
216
  export { USER_PROFILE_COLORS, USER_PROFILE_COLOR_PRESETS, FREE_USER_PROFILE_COLOR_PRESETS, } from './profileColors.generated.js';
214
217
  export { utf16MinLength, utf16MaxLength, utf16Length, isoDateTime, urlCheck, } from './stringChecks.js';
@@ -0,0 +1,97 @@
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 { applicationWebOriginSchema, oxyosDesktopEntryIdSchema, platformHostSchema, } from './appAssertions.js';
17
+ 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.js';
18
+ import { isoDateTime, utf16MaxLength, utf16MinLength } from './stringChecks.js';
19
+ export { APP_TOKEN_DEVICE_ACCESS_DENIED, DEVICE_APP_TOKEN_ERROR_CODES, DEVICE_APP_TOKEN_TTL_SECONDS, OXYOS_DESKTOP_ENTRY_ID_PATTERN, PLATFORM_HOSTS, };
20
+ const publicClientIdSchema = z.string().check(utf16MinLength(1)).check(utf16MaxLength(256));
21
+ /**
22
+ * Names the platform on its own password sign-in, and on the second factor
23
+ * completing it. Honoured only when the request has NO web `Origin` and
24
+ * `clientId` is a live public client id of an active Oxy application whose
25
+ * registry entry declares `platformHost` equal to `platform`; anything else is
26
+ * refused with the ordinary invalid-request answer before any account lookup or
27
+ * password work. When honoured, the device credential the sign-in returns is a
28
+ * platform credential, and a credential the sign-in's `device` proof presented
29
+ * is retired.
30
+ */
31
+ export const platformClientSchema = z.strictObject({
32
+ platform: platformHostSchema,
33
+ clientId: publicClientIdSchema,
34
+ });
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 const deviceAppTokenAttestationSchema = z.union([
46
+ z.strictObject({ platform: z.literal('oxyos'), desktopEntryId: oxyosDesktopEntryIdSchema }),
47
+ z.strictObject({ platform: platformHostSchema, self: z.literal(true) }),
48
+ z.strictObject({
49
+ platform: z.literal('astro'),
50
+ origin: applicationWebOriginSchema,
51
+ clientId: publicClientIdSchema,
52
+ }),
53
+ ]);
54
+ /**
55
+ * `POST /session/device/app-token`: the platform credential (no bearer;
56
+ * possession is the proof, as at `POST /session/device/token`), the
57
+ * attestation, and optionally `accountId` (pins the account, as that mint's
58
+ * does) and `clientId` (when given, a public client id of the SAME application
59
+ * the attestation names).
60
+ */
61
+ export const deviceAppTokenRequestSchema = z.strictObject({
62
+ deviceId: z.string().check(utf16MinLength(1)).check(utf16MaxLength(128)),
63
+ deviceSecret: z.string().check(utf16MinLength(1)).check(utf16MaxLength(256)),
64
+ accountId: z.string().check(utf16MinLength(1)).check(utf16MaxLength(128)).optional(),
65
+ clientId: publicClientIdSchema.optional(),
66
+ attestation: deviceAppTokenAttestationSchema,
67
+ });
68
+ /**
69
+ * The application's token: a fresh access token of the device's shared session
70
+ * for `accountId`, named for `applicationId` (`azp`, its public client id) and
71
+ * carrying `host`. `expiresAt` is the token's own `exp`
72
+ * ({@link DEVICE_APP_TOKEN_TTL_SECONDS} after it was minted).
73
+ */
74
+ export const deviceAppTokenResponseSchema = z.object({
75
+ accessToken: z.string().check(utf16MinLength(1)),
76
+ expiresAt: z.string().check(isoDateTime()),
77
+ applicationId: z.string().check(utf16MinLength(1)),
78
+ accountId: z.string().check(utf16MinLength(1)),
79
+ });
80
+ /**
81
+ * The `host` claim of an application token: the platform that vouched for the
82
+ * application and the id of its platform credential. Oxy re-checks both on
83
+ * every request (the credential is live and the platform's, `azp` is a live
84
+ * public client of an active Oxy application).
85
+ */
86
+ export const hostTokenClaimSchema = z.strictObject({
87
+ platform: platformHostSchema,
88
+ credential: z.string().check(utf16MinLength(1)).check(utf16MaxLength(128)),
89
+ });
90
+ /**
91
+ * What `GET /session/validate-header/:sessionId` adds for an application token:
92
+ * the application it is named for and the platform that vouched for it.
93
+ */
94
+ export const hostTokenValidationSchema = z.object({
95
+ applicationId: z.string().check(utf16MinLength(1)),
96
+ platform: platformHostSchema,
97
+ });
@@ -36,6 +36,7 @@ import { utf16MaxLength, utf16MinLength } from './stringChecks.js';
36
36
  import { z } from 'zod';
37
37
  import { EMAIL_CODE_LENGTH, emailAddressSchema, emailTicketSchema } from './accountEmail.js';
38
38
  import { deviceProofSchema } from './deviceSession.js';
39
+ import { platformClientSchema } from './platformSession.js';
39
40
  // The Zod-free half of this contract lives in `./client/` (`@oxy.so/contracts/client`);
40
41
  // it is re-exported here so the root entry is unchanged.
41
42
  import { PASSWORD_MIN_LENGTH, PASSWORD_MAX_LENGTH, SECOND_FACTOR_CODE_MAX_LENGTH, SIGN_IN_IDENTIFIER_MAX_LENGTH, TOTP_DIGITS, TOTP_BACKUP_CODE_COUNT, EMAIL_SIGNIN_LONG_CODE_ALPHABET, EMAIL_SIGNIN_LONG_CODE_LENGTH, normalizeEmailSignInCode, EMAIL_ACCOUNTS_MAX, REAUTH_ACTIONS, } from './client/signIn.js';
@@ -148,20 +149,29 @@ export const emailSignInLinkRequestSchema = z
148
149
  export const emailSignInLinkResponseSchema = z.object({
149
150
  approved: z.literal(true),
150
151
  });
151
- /** `POST /auth/signin/password` */
152
+ /**
153
+ * `POST /auth/signin/password`. `platformClient` is a platform's own sign-in
154
+ * (ADR 0058): see `platformClientSchema`.
155
+ */
152
156
  export const passwordSignInRequestSchema = z
153
157
  .object({
154
158
  identifier: signInIdentifierSchema,
155
159
  password: passwordInputSchema,
156
160
  ...sessionEnvelope,
161
+ platformClient: platformClientSchema.optional(),
157
162
  })
158
163
  .strict();
159
- /** `POST /auth/signin/second-factor` */
164
+ /**
165
+ * `POST /auth/signin/second-factor`. A challenge a platform's sign-in received
166
+ * is completed naming the SAME `platformClient`, and one that named none
167
+ * naming none.
168
+ */
160
169
  export const secondFactorSignInRequestSchema = z
161
170
  .object({
162
171
  challengeId: opaqueTokenSchema,
163
172
  code: secondFactorCodeSchema,
164
173
  ...sessionEnvelope,
174
+ platformClient: platformClientSchema.optional(),
165
175
  })
166
176
  .strict();
167
177
  /** `POST /auth/signup` — the account, from a username and a confirmed email. */
@@ -30,7 +30,7 @@ import { isoDateTime } from './stringChecks.js';
30
30
  * `require()`).
31
31
  */
32
32
  import { z } from 'zod';
33
- import { PROFILE_LINKS_MAX } from './client/userResponse.js';
33
+ import { PRONOUNS, PROFILE_LINKS_MAX } from './client/userResponse.js';
34
34
  import { verifiedDomainSchema } from './identity.js';
35
35
  import { accountCategoriesSchema, accountKindSchema } from './accountGraph.js';
36
36
  import { avatarCharacterSchema } from './avatarCharacter.js';
@@ -243,6 +243,7 @@ export const userResponseSchema = z
243
243
  .optional(),
244
244
  })
245
245
  .passthrough();
246
+ export const pronounsSchema = z.enum(PRONOUNS);
246
247
  export const userProfileUpdateSchema = z
247
248
  .object({
248
249
  name: z
@@ -262,6 +263,7 @@ export const userProfileUpdateSchema = z
262
263
  avatar: z.string().optional(),
263
264
  color: z.string().nullable().optional(),
264
265
  bio: z.string().optional(),
266
+ pronouns: pronounsSchema.optional(),
265
267
  description: z.string().optional(),
266
268
  phone: z.string().optional(),
267
269
  address: z.string().optional(),