@descix/platform-api 2.0.0 → 2.1.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 +6 -1
- package/src/entitlements/index.js +53 -32
- package/src/index.js +5 -0
- package/src/mcp-tools/nativeTools.js +1 -1
package/package.json
CHANGED
|
@@ -1,7 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@descix/platform-api",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.1.0",
|
|
4
4
|
"description": "Shared platform infrastructure: Firestore models, auth/session, permissions, entitlements, email",
|
|
5
|
+
"repository": {
|
|
6
|
+
"type": "git",
|
|
7
|
+
"url": "git+https://github.com/DeSciX/DeSciXCore.git",
|
|
8
|
+
"directory": "descix-platform-api"
|
|
9
|
+
},
|
|
5
10
|
"type": "module",
|
|
6
11
|
"main": "src/index.js",
|
|
7
12
|
"exports": {
|
|
@@ -31,56 +31,77 @@ export class AppNotFoundError extends Error {
|
|
|
31
31
|
}
|
|
32
32
|
|
|
33
33
|
/**
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
* The Products/{app_id} document is the canonical O(1) registry entry.
|
|
37
|
-
* app_id is globally unique; community_id is stored metadata in the doc.
|
|
38
|
-
* This function mutates params.community_id in-place.
|
|
34
|
+
* THE ONE DERIVATION of "which community owns this app".
|
|
39
35
|
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
36
|
+
* Reads Products/{app_id} — the canonical O(1) registry entry — and returns that
|
|
37
|
+
* community_id. It takes an app_id SCALAR, never a params bag, so there is no
|
|
38
|
+
* client-supplied community_id in scope for it to honour: the answer is a function
|
|
39
|
+
* of the registry alone. Every security boundary (authorization scope, Pinecone
|
|
40
|
+
* namespace, entitlement checks) MUST consume this rather than reading a
|
|
41
|
+
* community_id off a request.
|
|
43
42
|
*
|
|
44
43
|
* Resolution is authoritative and explicit (no silent default — anti-pattern #7):
|
|
45
|
-
* -
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
* - Genuine infrastructure errors (Firestore unreachable, etc.) are re-thrown as-is
|
|
49
|
-
* so they surface as 500s — not masked as "app not found".
|
|
44
|
+
* - No Products/{app_id} doc, or no resolvable community_id in it → AppNotFoundError (404).
|
|
45
|
+
* - Genuine infrastructure errors (Firestore unreachable) are re-thrown as-is so they
|
|
46
|
+
* surface as 500s — not masked as "app not found".
|
|
50
47
|
*
|
|
51
|
-
* @param {
|
|
52
|
-
* @
|
|
48
|
+
* @param {string} app_id
|
|
49
|
+
* @param {Object} [deps] - Seam for tests: { getProductData(app_id) => data|null }.
|
|
50
|
+
* Production callers pass nothing and get the Firestore path.
|
|
51
|
+
* @returns {Promise<string>} the registry's community_id for this app
|
|
53
52
|
* @throws {AppNotFoundError} when app_id is not registered in the current env
|
|
54
53
|
*/
|
|
55
|
-
export async function
|
|
56
|
-
if (!
|
|
54
|
+
export async function resolveAppCommunityId(app_id, deps = {}) {
|
|
55
|
+
if (!app_id) {
|
|
56
|
+
throw new AppNotFoundError(app_id, process.env.DEPLOY_ENV);
|
|
57
|
+
}
|
|
57
58
|
|
|
58
|
-
let
|
|
59
|
+
let productData;
|
|
59
60
|
try {
|
|
60
|
-
|
|
61
|
-
|
|
61
|
+
if (deps.getProductData) {
|
|
62
|
+
productData = await deps.getProductData(app_id);
|
|
63
|
+
} else {
|
|
64
|
+
const db = new CacheFirestore();
|
|
65
|
+
const productDoc = await db.db.collection('Products').doc(app_id).get();
|
|
66
|
+
productData = productDoc.exists ? productDoc.data() : null;
|
|
67
|
+
}
|
|
62
68
|
} catch (err) {
|
|
63
69
|
// Infrastructure failure (e.g. Firestore unreachable) — NOT a missing app.
|
|
64
70
|
// Re-throw so it surfaces as a 500 rather than a misleading 404.
|
|
65
|
-
console.error(`[
|
|
71
|
+
console.error(`[resolveAppCommunityId] Firestore error resolving '${app_id}': ${err.message}`);
|
|
66
72
|
throw err;
|
|
67
73
|
}
|
|
68
74
|
|
|
69
|
-
if (
|
|
70
|
-
|
|
71
|
-
if (productData.community_id) {
|
|
72
|
-
params.community_id = productData.community_id;
|
|
73
|
-
return;
|
|
74
|
-
}
|
|
75
|
+
if (productData) {
|
|
76
|
+
if (productData.community_id) return productData.community_id;
|
|
75
77
|
const match = productData.productPath?.match(/Community\/([^/]+)/);
|
|
76
|
-
if (match)
|
|
77
|
-
params.community_id = match[1];
|
|
78
|
-
return;
|
|
79
|
-
}
|
|
78
|
+
if (match) return match[1];
|
|
80
79
|
}
|
|
81
80
|
|
|
82
81
|
// App is not registered in this environment (or its Products doc is malformed).
|
|
83
82
|
// Surface a clean, structured 404 instead of letting an undefined community_id
|
|
84
83
|
// bubble into an opaque downstream 500.
|
|
85
|
-
throw new AppNotFoundError(
|
|
84
|
+
throw new AppNotFoundError(app_id, process.env.DEPLOY_ENV);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Hydrate community_id from the Products registry when missing.
|
|
89
|
+
*
|
|
90
|
+
* FILL-IF-ABSENT convenience for handlers that accept a community_id in their own
|
|
91
|
+
* published contract. It consumes resolveAppCommunityId so there is exactly one
|
|
92
|
+
* derivation of the fact.
|
|
93
|
+
*
|
|
94
|
+
* NOT AN AUTHORIZATION PRIMITIVE, and it never was: because it returns early when
|
|
95
|
+
* the caller already supplied a community_id, it is a no-op EXACTLY when a caller
|
|
96
|
+
* asserts the value — a mitigation that disables itself under the case that matters.
|
|
97
|
+
* An authorization scope MUST call resolveAppCommunityId directly.
|
|
98
|
+
*
|
|
99
|
+
* @param {Object} params - Mutable params object with app_id; sets community_id if missing
|
|
100
|
+
* @param {Object} [deps] - Seam for tests, forwarded to resolveAppCommunityId.
|
|
101
|
+
* @returns {Promise<void>}
|
|
102
|
+
* @throws {AppNotFoundError} when app_id is not registered in the current env
|
|
103
|
+
*/
|
|
104
|
+
export async function hydrateCommunityIdFromProducts(params, deps = {}) {
|
|
105
|
+
if (!params.app_id || params.community_id) return;
|
|
106
|
+
params.community_id = await resolveAppCommunityId(params.app_id, deps);
|
|
86
107
|
}
|
package/src/index.js
CHANGED
|
@@ -59,7 +59,12 @@ export {
|
|
|
59
59
|
} from './permissions/index.js';
|
|
60
60
|
|
|
61
61
|
// Entitlements
|
|
62
|
+
// resolveAppCommunityId is the AUTHORITATIVE derivation (app_id -> owning community, no request
|
|
63
|
+
// value consulted) and is what a security boundary must consume. hydrateCommunityIdFromProducts is
|
|
64
|
+
// the fill-if-absent convenience beside it. Exporting only the latter pointed every reader of this
|
|
65
|
+
// barrel at the one that is explicitly NOT an authorization primitive.
|
|
62
66
|
export {
|
|
67
|
+
resolveAppCommunityId,
|
|
63
68
|
hydrateCommunityIdFromProducts
|
|
64
69
|
} from './entitlements/index.js';
|
|
65
70
|
|
|
@@ -701,7 +701,7 @@ export const NATIVE_MCP_TOOLS = Object.freeze([
|
|
|
701
701
|
},
|
|
702
702
|
{
|
|
703
703
|
name: 'fabric_contract_put',
|
|
704
|
-
description: 'Write a CONTRACT — the agreement its parties sign, and the record a doer works under. `contract_key` IS THE FULL STORED KEY, prefix and all: it must already start with "' + KEY_CONTRACT + '" and it is written through UNTOUCHED — nothing is prepended and nothing is stripped, so the key you send is the key that exists and the contract has exactly ONE name. A value without the prefix is REFUSED BY NAME (FABRIC_CONTRACT_KEY_INVALID), and the refusal shows the key you probably meant; a client-supplied file_id/key is REFUSED separately. A CONTRACT IS NOT AN ENVELOPE: an envelope is the 1:1 assignment of a workstream to a seat and there is exactly one per workstream, while a workstream carries as many contracts as it has parties — a parent and a sub-contract per doer. Before this verb existed every contract on the fabric was written by raw app_records_put with no key derivation and no validation at all (measured 2026-08-26); that path is refused now, by name, pointing here. `mode` is REQUIRED and has NO DEFAULT, like every keyed write on this surface. The clocks are the server\'s — a caller-supplied created_at/occurred_at/received_at is refused. CONTRACT SHAPE: ' + ENVELOPE_TEXT_SHAPE + ' Prose is REFUSED (FABRIC_ENVELOPE_TEXT_NOT_SECTIONED) and a sectioned body missing rows is refused naming EXACTLY which (FABRIC_ENVELOPE_SECTIONS_MISSING) — the SAME validator fabric_envelope_put runs, not a second copy of it. TWO FURTHER RULES APPLY ONLY TO CONTRACTS, because a contract is what a doer grounds against: `knowledge.reads` must be a NON-EMPTY ARRAY whose entries each carry ' + CONTRACT_READ_FIELD_NAMES.join(', ') + ' (FABRIC_CONTRACT_KNOWLEDGE_READS_MISSING, naming the offending index and field), and `principles_carried` must be a NON-EMPTY ARRAY of non-empty strings (FABRIC_CONTRACT_PRINCIPLES_EMPTY). A contract whose knowledge section DESCRIBES how to read instead of LISTING what to read gives the doer nothing to execute and the verifier nothing to check a grounding record against — "read" (singular, a string) is the measured near-miss and is refused as one. Both rules fire ONLY on a write of `text`, so contracts written before they existed stay patchable and are re-cut by their authors rather than becoming unreachable.',
|
|
704
|
+
description: 'Write a CONTRACT — the agreement its parties sign, and the record a doer works under. READ IT BACK with `app_records_get` ({app_id: "egpt-frqtl", kb_id: "coordination", file_ids: [contract_key]}) — there is no `fabric_contract_get`; this is the one, deliberate read path for a contract this verb writes (VISION ruling 2026-08-31, contract-defect-contract-read-plane-divergence). `contract_key` IS THE FULL STORED KEY, prefix and all: it must already start with "' + KEY_CONTRACT + '" and it is written through UNTOUCHED — nothing is prepended and nothing is stripped, so the key you send is the key that exists and the contract has exactly ONE name. A value without the prefix is REFUSED BY NAME (FABRIC_CONTRACT_KEY_INVALID), and the refusal shows the key you probably meant; a client-supplied file_id/key is REFUSED separately. A CONTRACT IS NOT AN ENVELOPE: an envelope is the 1:1 assignment of a workstream to a seat and there is exactly one per workstream, while a workstream carries as many contracts as it has parties — a parent and a sub-contract per doer. Before this verb existed every contract on the fabric was written by raw app_records_put with no key derivation and no validation at all (measured 2026-08-26); that path is refused now, by name, pointing here. `mode` is REQUIRED and has NO DEFAULT, like every keyed write on this surface. The clocks are the server\'s — a caller-supplied created_at/occurred_at/received_at is refused. CONTRACT SHAPE: ' + ENVELOPE_TEXT_SHAPE + ' Prose is REFUSED (FABRIC_ENVELOPE_TEXT_NOT_SECTIONED) and a sectioned body missing rows is refused naming EXACTLY which (FABRIC_ENVELOPE_SECTIONS_MISSING) — the SAME validator fabric_envelope_put runs, not a second copy of it. TWO FURTHER RULES APPLY ONLY TO CONTRACTS, because a contract is what a doer grounds against: `knowledge.reads` must be a NON-EMPTY ARRAY whose entries each carry ' + CONTRACT_READ_FIELD_NAMES.join(', ') + ' (FABRIC_CONTRACT_KNOWLEDGE_READS_MISSING, naming the offending index and field), and `principles_carried` must be a NON-EMPTY ARRAY of non-empty strings (FABRIC_CONTRACT_PRINCIPLES_EMPTY). A contract whose knowledge section DESCRIBES how to read instead of LISTING what to read gives the doer nothing to execute and the verifier nothing to check a grounding record against — "read" (singular, a string) is the measured near-miss and is refused as one. Both rules fire ONLY on a write of `text`, so contracts written before they existed stay patchable and are re-cut by their authors rather than becoming unreachable.',
|
|
705
705
|
mutating: true,
|
|
706
706
|
inputSchema: {
|
|
707
707
|
type: 'object',
|