@descix/platform-api 2.0.1 → 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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@descix/platform-api",
3
- "version": "2.0.1",
3
+ "version": "2.1.0",
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
 
@@ -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',