@descix/platform-api 2.0.1 → 2.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 +1 -1
- package/src/entitlements/index.js +53 -32
- package/src/index.js +5 -0
- package/src/mcp-tools/nativeTools.js +2 -2
package/package.json
CHANGED
|
@@ -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
|
|
|
@@ -161,7 +161,7 @@ export const NATIVE_MCP_TOOLS = Object.freeze([
|
|
|
161
161
|
// document-scoping ones). Declared so strict validation admits them.
|
|
162
162
|
intelligence_level: { type: 'number', description: 'Intelligence level 1-5. A level selects a (model, thinking) PAIR, not just a model tier — higher levels cost more AI credits. ' + MODEL_THINKING_CHAIN },
|
|
163
163
|
model: { type: 'string', description: 'Explicit model name. It overrides the whole chain below, and because you changed the model it carries NO inherited thinking setting — pass thinking_budget too if this model needs one. Prefer intelligence_level unless you need one specific model. ' + MODEL_THINKING_CHAIN },
|
|
164
|
-
thinking_budget: { type: 'number', description: 'Thinking-token budget for THIS call: -1 dynamic, 0 off, N a fixed cap. It is the request tier\'s thinking statement and wins over whatever the chain resolved. Omit to take the thinking setting from the same tier that supplied the model. ' + MODEL_THINKING_CHAIN },
|
|
164
|
+
thinking_budget: { type: 'number', description: 'Thinking-token budget for THIS call: -1 dynamic, 0 off, N a fixed cap. The number is mapped onto the provider\'s thinking LEVEL, and which levels exist is a property of the MODEL: on a model whose vocabulary is {high, low} (measured: gemini-2.5-flash, gemini-2.5-pro) there is no "off", so 0 is REFUSED naming the model and its allowed values rather than sent onward. Thinking is also spent from max_output_tokens, so a cap too small to fit it is refused too. It is the request tier\'s thinking statement and wins over whatever the chain resolved. Omit to take the thinking setting from the same tier that supplied the model. ' + MODEL_THINKING_CHAIN },
|
|
165
165
|
temperature: { type: 'number', description: 'Generation temperature override. Omit to inherit the KB/platform default.' },
|
|
166
166
|
max_output_tokens: { type: 'number', description: 'Cap on generated tokens for this call. Omit to inherit the KB/platform default.' },
|
|
167
167
|
streaming: { type: 'boolean', description: 'Stream the reply instead of returning it whole. Leave unset/false over MCP tools/call, which returns a single result — this exists for the streaming transports (PWA/Discord).' },
|
|
@@ -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',
|