@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@descix/platform-api",
3
- "version": "2.0.1",
3
+ "version": "2.1.1",
4
4
  "description": "Shared platform infrastructure: Firestore models, auth/session, permissions, entitlements, email",
5
5
  "repository": {
6
6
  "type": "git",
@@ -31,56 +31,77 @@ export class AppNotFoundError extends Error {
31
31
  }
32
32
 
33
33
  /**
34
- * Hydrate community_id from the Products registry when missing.
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
- * Invariant: Never trust a client-provided community_id.
41
- * Security boundaries (Pinecone namespace, entitlement checks) must always
42
- * call this to re-derive community_id from the Products registry.
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
- * - If app_id has no Products/{app_id} doc (or no resolvable community_id in it),
46
- * throw AppNotFoundError (HTTP 404). This covers the wrong-env / nonexistent-app
47
- * case for every chat/RAG/KB query path, all of which funnel through here.
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 {Object} params - Mutable params object with app_id; sets community_id if missing
52
- * @returns {Promise<void>}
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 hydrateCommunityIdFromProducts(params) {
56
- if (!params.app_id || params.community_id) return;
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 productDoc;
59
+ let productData;
59
60
  try {
60
- const db = new CacheFirestore();
61
- productDoc = await db.db.collection('Products').doc(params.app_id).get();
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(`[hydrateCommunityIdFromProducts] Firestore error resolving '${params.app_id}': ${err.message}`);
71
+ console.error(`[resolveAppCommunityId] Firestore error resolving '${app_id}': ${err.message}`);
66
72
  throw err;
67
73
  }
68
74
 
69
- if (productDoc.exists) {
70
- const productData = productDoc.data();
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(params.app_id, process.env.DEPLOY_ENV);
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',