@descix/platform-api 5.1.0 → 5.2.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@descix/platform-api",
3
- "version": "5.1.0",
3
+ "version": "5.2.0",
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
@@ -118,6 +118,59 @@
118
118
  "options": [],
119
119
  "runbookAnchor": null
120
120
  },
121
+ {
122
+ "verbPath": "app media-delete",
123
+ "description": "Delete uploaded media from an app's assets/ prefix, one path per server call; a path that does not exist is reported and the rest still run (exit 1 only when a call fails)",
124
+ "arguments": [
125
+ {
126
+ "name": "path",
127
+ "required": true,
128
+ "variadic": true,
129
+ "description": "One or more object paths relative to the app assets/ prefix, as media-list prints them"
130
+ }
131
+ ],
132
+ "options": [
133
+ {
134
+ "flags": "-a, --app <id>",
135
+ "description": "App ID (community is resolved server-side from Products)",
136
+ "required": true
137
+ },
138
+ {
139
+ "flags": "--dry-run",
140
+ "description": "Ask the server what would be deleted; nothing is deleted",
141
+ "required": false
142
+ },
143
+ {
144
+ "flags": "--json",
145
+ "description": "Print every per-path server result and the summary as JSON (for scripting)",
146
+ "required": false
147
+ }
148
+ ],
149
+ "runbookAnchor": null
150
+ },
151
+ {
152
+ "verbPath": "app media-list",
153
+ "description": "List an app's uploaded media (path, size, content type, updated, public_url) and its storage total against the quota",
154
+ "arguments": [],
155
+ "options": [
156
+ {
157
+ "flags": "-a, --app <id>",
158
+ "description": "App ID (community is resolved server-side from Products)",
159
+ "required": true
160
+ },
161
+ {
162
+ "flags": "--prefix <relPath>",
163
+ "description": "Only objects under this sub-path of the app assets/ prefix (e.g. \"shows/myshow\")",
164
+ "required": false
165
+ },
166
+ {
167
+ "flags": "--json",
168
+ "description": "Print the server's listing object unchanged (for scripting)",
169
+ "required": false
170
+ }
171
+ ],
172
+ "runbookAnchor": null
173
+ },
121
174
  {
122
175
  "verbPath": "app media-upload",
123
176
  "description": "Upload media/asset files to an app's GCS assets prefix (200 MB per app today; app owners, community admins and platform admins may upload — returns asset references)",
@@ -1713,18 +1766,23 @@
1713
1766
  },
1714
1767
  {
1715
1768
  "verbPath": "referral create",
1716
- "description": "Generate a referral code for a community/app",
1769
+ "description": "Get your share link to a page: <page>?ref=<code> (the same link each time you ask)",
1717
1770
  "arguments": [],
1718
1771
  "options": [
1719
1772
  {
1720
- "flags": "-c, --community <id>",
1721
- "description": "Community ID",
1773
+ "flags": "--url <page>",
1774
+ "description": "The page to share: an https URL on the platform domain (the query is dropped)",
1722
1775
  "required": true
1723
1776
  },
1724
1777
  {
1725
- "flags": "-a, --app <id>",
1726
- "description": "App ID (optional)",
1727
- "required": false
1778
+ "flags": "--channel <channel>",
1779
+ "description": "How the link travels, e.g. web_share or email (the server names the accepted values)",
1780
+ "required": true
1781
+ },
1782
+ {
1783
+ "flags": "-c, --community <id>",
1784
+ "description": "The community the referral credits",
1785
+ "required": true
1728
1786
  }
1729
1787
  ],
1730
1788
  "runbookAnchor": null
@@ -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;