@descix/platform-api 5.1.0 → 5.1.1

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": "@descix/platform-api",
3
- "version": "5.1.0",
3
+ "version": "5.1.1",
4
4
  "description": "Shared platform infrastructure: Firestore models, auth/session, permissions, entitlements, email",
5
5
  "repository": {
6
6
  "type": "git",
@@ -11,7 +11,8 @@
11
11
  "main": "src/index.js",
12
12
  "scripts": {
13
13
  "test:migration-receipt-email": "node --test --experimental-test-module-mocks tests/migration-receipt-email.test.js",
14
- "test:email-identity": "node --test --experimental-test-module-mocks tests/email-identity-owner.test.js"
14
+ "test:email-identity": "node --test --experimental-test-module-mocks tests/email-identity-owner.test.js",
15
+ "test:user-recovery": "node --test --experimental-test-module-mocks tests/user-recovery-confirmed-owner.test.js"
15
16
  },
16
17
  "exports": {
17
18
  ".": "./src/index.js",
@@ -41,7 +42,7 @@
41
42
  "node": ">=24.0.0"
42
43
  },
43
44
  "dependencies": {
44
- "@descix/cloud-core": "^2.0.0",
45
+ "@descix/cloud-core": "^2.0.4",
45
46
  "google-auth-library": "^10.5.0",
46
47
  "googleapis": "^169.0.0"
47
48
  }
@@ -5,9 +5,17 @@
5
5
  * Generates codes, stores hashed values in Firestore, sends via Gmail.
6
6
  *
7
7
  * Config values loaded at call time via getCloudConfig() from @descix/cloud-core.
8
+ *
9
+ * Local code sink: on a developer machine only, sendEmailVerification ALSO appends the plain code
10
+ * to the JSON-lines file named by LOCAL_VERIFICATION_CODE_SINK, so a local end-to-end spec can
11
+ * complete email verification without a mailbox. The key is a cloud-core local-only key
12
+ * (config-schema.json local_only_keys): admitted only from dev-overrides.json when
13
+ * isManagedCloudRuntime is false, and refused at boot everywhere else.
8
14
  */
9
15
 
10
16
  import crypto from 'crypto';
17
+ import fs from 'fs';
18
+ import path from 'path';
11
19
  import {
12
20
  CacheFirestore,
13
21
  FirestoreCollections,
@@ -62,9 +70,67 @@ function verificationRefusal(code, message) {
62
70
  });
63
71
  }
64
72
 
73
+ /** The config key naming the local code sink file (a cloud-core local-only key). */
74
+ export const LOCAL_VERIFICATION_CODE_SINK_KEY = 'LOCAL_VERIFICATION_CODE_SINK';
75
+
76
+ /**
77
+ * The local code sink path of this process, or null when it has none. Throws when the key is set
78
+ * on a managed cloud runtime (cloud-core refuses that config at boot; reaching here means the
79
+ * refusal was bypassed) or is not an absolute path. Resolved BEFORE any side effect of a send.
80
+ */
81
+ function localVerificationCodeSink(utils) {
82
+ const sinkPath = utils[LOCAL_VERIFICATION_CODE_SINK_KEY];
83
+ if (sinkPath === undefined || sinkPath === null) return null;
84
+ if (utils.isManagedCloudRuntime !== false) {
85
+ throw new Error(`${LOCAL_VERIFICATION_CODE_SINK_KEY} is set but this process is not on a developer machine ` +
86
+ `(isManagedCloudRuntime=${utils.isManagedCloudRuntime}); refusing to send a verification code.`);
87
+ }
88
+ if (typeof sinkPath !== 'string' || !path.isAbsolute(sinkPath)) {
89
+ throw new Error(`${LOCAL_VERIFICATION_CODE_SINK_KEY} must be an absolute file path (dev-overrides.json); ` +
90
+ `got ${JSON.stringify(sinkPath)}.`);
91
+ }
92
+ return sinkPath;
93
+ }
94
+
95
+ /**
96
+ * Append one sent code to the local code sink at `sinkPath` (from localVerificationCodeSink).
97
+ * The file is created by this function with mode 600 (parent directories 700); an existing file
98
+ * readable by group or other is refused, never silently used. The code is never logged.
99
+ *
100
+ * Line contract (JSON, one object per line):
101
+ * { email, code, requested_by, expires_at, timestamp }
102
+ * email normalized address (the EMAIL_VERIFICATIONS doc id)
103
+ * code the plain 6-digit code verifyEmailCode accepts
104
+ * requested_by the requesting account's uid, or null for an account-less send
105
+ * expires_at ISO-8601 expiry of the code
106
+ * timestamp ISO-8601 time the line was written
107
+ * The newest line for an email is the live code: every send replaces the stored hash.
108
+ */
109
+ function writeLocalVerificationCode(sinkPath, { email, code, uid, expiresAt }) {
110
+ fs.mkdirSync(path.dirname(sinkPath), { recursive: true, mode: 0o700 });
111
+ const fd = fs.openSync(sinkPath, 'a', 0o600);
112
+ try {
113
+ const mode = fs.fstatSync(fd).mode & 0o777;
114
+ if (mode & 0o077) {
115
+ throw new Error(`${LOCAL_VERIFICATION_CODE_SINK_KEY} file ${sinkPath} has mode ${mode.toString(8)}; ` +
116
+ 'it must be 600. Delete it and let the sink create it.');
117
+ }
118
+ fs.writeSync(fd, JSON.stringify({
119
+ email,
120
+ code,
121
+ requested_by: uid,
122
+ expires_at: expiresAt.toISOString(),
123
+ timestamp: new Date().toISOString(),
124
+ }) + '\n');
125
+ } finally {
126
+ fs.closeSync(fd);
127
+ }
128
+ }
129
+
65
130
  /**
66
131
  * Send an email verification code to the given address.
67
- * Generates a 6-digit code, hashes and stores it in Firestore, then emails it.
132
+ * Generates a 6-digit code, hashes and stores it in Firestore, then emails it; on a developer
133
+ * machine with LOCAL_VERIFICATION_CODE_SINK set, also appends it to the local code sink.
68
134
  *
69
135
  * The record is bound to the requesting account: `uid` is stored on it (null for flows with no
70
136
  * account, e.g. Discord link or a token-claim recipient), and every send rewrites it, so a new
@@ -92,6 +158,8 @@ export async function sendEmailVerification(params) {
92
158
  );
93
159
  }
94
160
 
161
+ const sinkPath = localVerificationCodeSink(utils);
162
+
95
163
  const code = crypto.randomInt(100000, 999999).toString();
96
164
  const codeHash = crypto.createHash('sha256').update(code).digest('hex');
97
165
  const expiresAt = Timestamp.fromDate(new Date(Date.now() + EMAIL_CODE_EXPIRY_MINUTES * 60 * 1000));
@@ -109,6 +177,8 @@ export async function sendEmailVerification(params) {
109
177
 
110
178
  await sendVerificationEmail(normalized, code, EMAIL_CODE_EXPIRY_MINUTES);
111
179
 
180
+ if (sinkPath) writeLocalVerificationCode(sinkPath, { email: normalized, code, uid, expiresAt: expiresAt.toDate() });
181
+
112
182
  return networkResponse(NetworkStatus.OK, LoginStatus.CONNECTED, {
113
183
  sent: true,
114
184
  expires_in_minutes: EMAIL_CODE_EXPIRY_MINUTES
@@ -611,6 +611,7 @@ export class User {
611
611
  user.migrated_to = user_doc.migrated_to || null;
612
612
  user.migrated_at = user_doc.migrated_at || null;
613
613
  user.pending_referral_guild_id = user_doc.pending_referral_guild_id || null;
614
+ user.recovery_confirmed_at = user_doc.recovery_confirmed_at || null;
614
615
 
615
616
  return user;
616
617
  }
@@ -1099,6 +1100,24 @@ export class User {
1099
1100
  return !!this.tos_accepted_at;
1100
1101
  }
1101
1102
 
1103
+ /**
1104
+ * Wallet cold-storage backup (design 2026-10-23): the user confirmed "I have printed or written it
1105
+ * down" for the recovery sheet. Stores only when (ISO string); the sheet never reaches the server.
1106
+ */
1107
+ async confirmRecovery() {
1108
+ const recovery_confirmed_at = new Date().toISOString();
1109
+ const result = await this.db.update_doc_fields(FirestoreCollections.USERS(), this.id, { recovery_confirmed_at });
1110
+ if (result !== true) {
1111
+ throw new Error(`User.confirmRecovery: the USERS write for ${this.id} failed; recovery_confirmed_at was not stored`);
1112
+ }
1113
+ this.recovery_confirmed_at = recovery_confirmed_at;
1114
+ return recovery_confirmed_at;
1115
+ }
1116
+
1117
+ hasConfirmedRecovery() {
1118
+ return typeof this.recovery_confirmed_at === 'string' && this.recovery_confirmed_at.length > 0;
1119
+ }
1120
+
1102
1121
  async stampBaseEntitlements(stamp) {
1103
1122
  const updates = { base_entitlements_stamp: stamp };
1104
1123
  this.base_entitlements_stamp = stamp;