@vantageos/cloud-identity 0.1.0 → 0.3.0

package/dist/tenancy-domain.js

@@ -0,0 +1,148 @@
+/**
+ * @vantageos/cloud-identity 0.2.0 — Domain-tenancy layer.
+ *
+ * Additive-only: does not modify any 0.1.0 exports.
+ *
+ * Provides:
+ *   - WorkspaceRole literal union + Zod schema
+ *   - Workspace type + Zod schema
+ *   - WorkspaceMember type + Zod schema
+ *   - TenantContext type + Zod schema
+ *   - ScopeViolationError class (code: "SCOPE_VIOLATION")
+ *   - getEffectiveTenantId(ctx, args) — multi-tenant isolation guard
+ *   - decodeUnverifiedBearer(token) — DECODE-ONLY helper, NOT authentication.
+ *     The decoded payload is attacker-controlled. Production code MUST use a
+ *     signed JWT or opaque-token lookup before treating the payload as a
+ *     trust boundary.
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// WorkspaceRole
+// ---------------------------------------------------------------------------
+export const workspaceRoleSchema = z.enum(["Admin", "Editor", "Viewer"]);
+// ---------------------------------------------------------------------------
+// Workspace
+// ---------------------------------------------------------------------------
+export const workspaceSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    createdAt: z.number(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+// ---------------------------------------------------------------------------
+// WorkspaceMember
+// ---------------------------------------------------------------------------
+export const workspaceMemberSchema = z.object({
+    userId: z.string().min(1),
+    workspaceId: z.string().min(1),
+    role: workspaceRoleSchema,
+    joinedAt: z.number(),
+});
+// ---------------------------------------------------------------------------
+// TenantContext
+// ---------------------------------------------------------------------------
+export const tenantContextSchema = z.object({
+    workspaceId: z.string().min(1),
+    userId: z.string().min(1),
+    roles: z.array(workspaceRoleSchema),
+});
+/**
+ * Thrown by `getEffectiveTenantId` when `args.workspaceId` does not match the
+ * workspaceId encoded in the bearer-resolved `TenantContext`. This error is the
+ * canonical cross-tenant isolation signal across the VantagePeers Cloud fleet.
+ *
+ * Callers MUST translate this to a 403 or MCP permission-denied — never 404.
+ */
+export class ScopeViolationError extends Error {
+    code = "SCOPE_VIOLATION";
+    payload;
+    constructor(payload) {
+        super(`SCOPE_VIOLATION: requested tenant "${payload.requestedTenantId}" does not match context tenant "${payload.contextTenantId}" — ${payload.reason}`);
+        this.name = "ScopeViolationError";
+        this.payload = payload;
+        // Restore prototype chain (required for instanceof checks in transpiled targets).
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+// ---------------------------------------------------------------------------
+// getEffectiveTenantId
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the effective tenant workspace ID from a `TenantContext` + request args.
+ *
+ * If `args.workspaceId` differs from the context's `workspaceId` (derived from
+ * the bearer token), a `ScopeViolationError` is thrown immediately.
+ *
+ * This is the primary multi-tenant isolation gate — call it at the top of every
+ * MCP tool handler that accepts a `workspaceId` argument.
+ *
+ * @example
+ * ```ts
+ * const tenantId = getEffectiveTenantId(ctx, args);
+ * // safe to use tenantId for DB queries — caller's scope is verified
+ * ```
+ */
+export function getEffectiveTenantId(ctx, args) {
+    if (args.workspaceId !== ctx.workspaceId) {
+        throw new ScopeViolationError({
+            requestedTenantId: args.workspaceId,
+            contextTenantId: ctx.workspaceId,
+            reason: "args.workspaceId does not match bearer-resolved context workspaceId",
+        });
+    }
+    return ctx.workspaceId;
+}
+// ---------------------------------------------------------------------------
+// decodeUnverifiedBearer
+// ---------------------------------------------------------------------------
+/**
+ * @security ⚠️ DECODE-ONLY. NOT AUTHENTICATION. NOT A TRUST BOUNDARY.
+ *
+ * Decodes a `base64(JSON({ userId, workspaceId, roles[] }))` payload and
+ * validates its SHAPE with Zod. It performs NO signature verification, NO
+ * issuer check, NO expiry check, NO replay-attack protection. The decoded
+ * payload is attacker-controlled and MUST NOT be used as the source of
+ * truth for multi-tenant isolation.
+ *
+ * Forgery example: any attacker producing
+ *   base64(JSON({ userId:"x", workspaceId:"victim-org", roles:["Admin"] }))
+ * passes this function. Treating the returned `workspaceId` as authoritative
+ * — for example feeding it into `getEffectiveTenantId` as the trusted
+ * `ctx.workspaceId` — silently grants cross-tenant access.
+ *
+ * Use only as:
+ *   - test fixture / harness helper
+ *   - decoder for a bearer that was ALREADY verified by an upstream signed-JWT
+ *     middleware (the production trust boundary)
+ *
+ * For the production trust boundary, callers MUST substitute a signed JWT
+ * verifier (not yet exported by this package) or an opaque-token lookup
+ * against a Convex tenancy table.
+ *
+ * Renamed from `resolveBearer` (0.2.0 pre-release) to make the lack of
+ * verification impossible to miss at the call-site.
+ */
+const bearerPayloadSchema = z.object({
+    userId: z.string().min(1),
+    workspaceId: z.string().min(1),
+    roles: z.array(workspaceRoleSchema),
+});
+export async function decodeUnverifiedBearer(token) {
+    let raw;
+    try {
+        raw = Buffer.from(token, "base64").toString("utf-8");
+    }
+    catch {
+        throw new Error(`decodeUnverifiedBearer: failed to base64-decode token`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`decodeUnverifiedBearer: token payload is not valid JSON`);
+    }
+    // Zod parse — throws ZodError on schema violations (missing fields, bad roles).
+    return bearerPayloadSchema.parse(parsed);
+}
+//# sourceMappingURL=tenancy-domain.js.map

package/dist/tenancy-domain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenancy-domain.js","sourceRoot":"","sources":["../src/tenancy-domain.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/cloud-identity",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Framework-agnostic identity + scope-filter primitives for VantagePeers Cloud (multi-tenant MCP).",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,6 +25,10 @@
     "./types": {
       "types": "./dist/types.d.ts",
       "import": "./dist/types.js"
+    },
+    "./tenancy-domain": {
+      "types": "./dist/tenancy-domain.d.ts",
+      "import": "./dist/tenancy-domain.js"
     }
   },
   "files": [
@@ -49,7 +53,7 @@
     "identity"
   ],
   "author": "VantagePeers Cloud",
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vantageos-agency/cloud-identity.git"
@@ -68,5 +72,8 @@
     "@types/node": "^20.11.0",
     "typescript": "^5.4.0",
     "vitest": "^1.6.0"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
   }
 }